home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / archives / ckv201.zip / ckermit80.txt < prev    next >
Text File  |  2002-02-13  |  436KB  |  9,503 lines
  1.  
  2.                            C-Kermit 8.0 Update Notes
  3.                                        
  4.    [ [1]Contents ] [ [2]C-Kermit ] [ [3]Kermit Home ]
  5.    
  6.               Second Supplement to Using C-Kermit, Second Edition
  7.                                        
  8. For C-Kermit 8.0
  9.  
  10.    As of C-Kermit version: 8.0.201
  11.    Date of C-Kermit release: 8 Feb 2002
  12.    This file last updated: Wed Feb 13 12:31:50 2002
  13.    
  14.      IF YOU ARE READING A PLAIN-TEXT version of this document, note that
  15.      this file is a plain-text dump of a Web page. You can visit the
  16.      original (and possibly more up-to-date) Web page here:
  17.      
  18.   [4]http://www.columbia.edu/kermit/ckermit80.html
  19.  
  20. Authors: Frank da Cruz and Christine M. Gianone
  21. Address: The Kermit Project
  22.          Columbia University
  23.          612 West 115th Street
  24.          New York NY 10025-7799
  25.          USA
  26. Fax:     +1 (212) 662-6442
  27. E-Mail:  [5]kermit-support@columbia.edu
  28. Web:     [6]http://www.columbia.edu/kermit/
  29. Or:      [7]http://www.kermit-project.org/
  30. Or:      [8]http://www.columbia.nyc.ny.us/kermit/
  31.      _________________________________________________________________
  32.    
  33.   NOTICES
  34.   
  35.    This document:
  36.           Copyright ⌐ 1997, 2002, Frank da Cruz and Christine M. Gianone.
  37.           All rights reserved.
  38.           
  39.    Kermit 95:
  40.           Copyright ⌐ 1995, 2002, Trustees of Columbia University in the
  41.           City of New York. All rights reserved.
  42.           
  43.    C-Kermit:
  44.           Copyright ⌐ 1985, 2002,
  45.           Trustees of Columbia University in the City of New York. All
  46.           rights reserved. See the C-Kermit [9]COPYING.TXT file or the
  47.           copyright text in the [10]ckcmai.c module for disclaimer and
  48.           permissions.
  49.           
  50.    When Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or
  51.           SSL/TLS protocol are included:
  52.           Portions Copyright ⌐ 1990, Massachusetts Institute of
  53.           Technology.
  54.           Portions Copyright ⌐ 1991, 1993 Regents of the University of
  55.           California.
  56.           Portions Copyright ⌐ 1991, 1992, 1993, 1994, 1995 by AT&T.
  57.           Portions Copyright ⌐ 1997, Stanford University.
  58.           Portions Copyright ⌐ 1995-1997, Eric Young
  59.           <eay@cryptosoft.com>.
  60.           
  61.    For the full text of the third-party copyright notices, see
  62.    [11]Appendix V.
  63.      _________________________________________________________________
  64.    
  65.   WHAT IS IN THIS FILE
  66.   
  67.    This file lists changes made to C-Kermit since version 7.0 was
  68.    released in January 2000. Use this file as a supplement to:
  69.    
  70.      * The second edition of [12]Using C-Kermit; and:
  71.      * The [13]C-Kermit 7.0 Update Notes. Also available in plain-text
  72.        form as [14]ckermit70.txt.
  73.        
  74.    until the third edition of Using C-Kermit is published. We apologize
  75.    for the scattered documentation and will consolidate it when we are
  76.    able.
  77.      _________________________________________________________________
  78.    
  79.    ADDITIONAL FILES Several other files accompany this new Kermit
  80.    release:
  81.    
  82.    [15]ckututor.html
  83.           C-Kermit Tutorial (for Unix). Also distributed in Nroff form as
  84.           [16]ckuker.nr, the Unix C-Kermit manual page.
  85.           
  86.    [17]security80.html
  87.           Discussion of Kermit's new authentication and encryption
  88.           features, updated for C-Kermit 8.0.
  89.           
  90.    [18]telnet80.html
  91.           Detailed documentation of Kermit's Telnet client, updated for
  92.           C-Kermit 8.0.
  93.           
  94.    [19]ftpscripts.html
  95.           Tutorial: Writing FTP automation scripts
  96.           
  97.    [20]ckcbwr.html
  98.           Platform-independent C-Kermit hints and tips. Also distributed
  99.           in plain text form as [21]ckcbwr.txt
  100.           
  101.    [22]ckubwr.html
  102.           Unix-specific C-Kermit hints and tips. Also distributed in
  103.           plain text form as [23]ckubwr.txt.
  104.           
  105.    [24]ckvbwr.html
  106.           VMS-specific C-Kermit hints and tips. Also distributed in plain
  107.           text form as [25]ckvbwr.txt.
  108.           
  109.    [26]ckuins.html
  110.           Unix C-Kermit installation instructions. Also distributed in
  111.           plain text form as [27]ckuins.txt.
  112.           
  113.    [28]ckvins.html
  114.           VMS C-Kermit installation instructions. Also distributed in
  115.           plain text form as [29]ckvins.txt.
  116.           
  117.    [30]ckccfg.html
  118.           Compile-time configuration options. Also distributed in plain
  119.           text form as [31]ckccfg.txt.
  120.           
  121.    [32]ckcplm.html
  122.           C-Kermit Program Logic Manual. Also distributed in plain text
  123.           form as [33]ckcplm.txt.
  124.           
  125.    [34]iksd.html
  126.           Internet Kermit Service Aministrators Guide for Unix.
  127.           
  128.    [35]skermit.html
  129.           C-Kermit as an SSH Subsystem (SFTP server replacement).
  130.           
  131.    [ [36]Top ] [ [37]C-Kermit Home ] [ [38]Kermit Home ]
  132.   __________________________________________________________________________
  133.  
  134. CONTENTS
  135.  
  136.      [39]0. WHAT'S NEW
  137.      [40]1. FIXES SINCE VERSION 7.0.196
  138.      [41]2. SSH AND HTTP 
  139.          [42]2.1. SSH Connections
  140.          [43]2.2. HTTP Connections
  141.             [44]2.2.1. HTTP Command Switches
  142.             [45]2.2.2. HTTP Action Commands
  143.             [46]2.2.3. HTTP Headers
  144.             [47]2.2.4. Secure HTTP Connections
  145.             [48]2.2.5. HTTP Variables
  146.             [49]2.2.6. The HTTP Command-Line Personality
  147.      [50]3. THE BUILT-IN FTP CLIENT
  148.          [51]3.1. Making and Managing FTP Connections
  149.             [52]3.1.1. Kermit Command-Line Options for FTP
  150.             [53]3.1.2. The FTP Command-Line Personality
  151.             [54]3.1.3. The FTP URL Interpreter
  152.             [55]3.1.4. Interactive FTP Session Establishment
  153.          [56]3.2. Making Secure FTP Connections
  154.          [57]3.3. Setting FTP Preferences
  155.          [58]3.4. Managing Directories and Files
  156.          [59]3.5. Uploading Files With FTP
  157.             [60]3.5.1. FTP PUT Switches
  158.             [61]3.5.2. Update Mode
  159.             [62]3.5.3. Recovery
  160.          [63]3.6. Downloading Files With FTP
  161.             [64]3.6.1. FTP GET Switches
  162.             [65]3.6.2. Filename Collisions
  163.             [66]3.6.3. Recovery
  164.          [67]3.7. Translating Character Sets
  165.             [68]3.7.1. Character Sets and Uploading
  166.             [69]3.7.2. Character Sets and Downloading
  167.          [70]3.8. FTP Command Shortcuts
  168.          [71]3.9. Dual Sessions
  169.          [72]3.10. Automating FTP Sessions
  170.             [73]3.10.1. FTP-Specific Variables and Functions
  171.             [74]3.10.2. Examples
  172.          [75]3.11. Advanced FTP Protocol Features  [76]4. FILE SCANNING
  173.     [77]5. FILE AND DIRECTORY NAMES CONTAINING SPACES
  174.     [78]6. OTHER COMMAND PARSING IMPROVEMENTS
  175.          [79]6.1. Grouping Macro Arguments
  176.          [80]6.2. Directory and File Name Completion
  177.          [81]6.3. Passing Arguments to Command Files
  178.          [82]6.4. More-Prompting
  179.          [83]6.5. Commas in Macro Definitions
  180.          [84]6.6. Arrow Keys
  181.     [85]7. NEW COMMANDS AND SWITCHES
  182.     [86]8. SCRIPTING IMPROVEMENTS
  183.          [87]8.1. Performance and Debugging
  184.          [88]8.2. Using Macros as Numeric Variables
  185.          [89]8.3. New IF Conditions
  186.          [90]8.4. The ON_UNKNOWN_COMMAND Macro
  187.          [91]8.5. The SHOW MACRO Command
  188.          [92]8.6. Arrays
  189.          [93]8.7. New or Improved Built-in Variables and Functions
  190.          [94]8.8. The RETURN and END Commands
  191.          [95]8.9. UNDEFINing Groups of Variables
  192.          [96]8.10. The MINPUT Command
  193.          [97]8.11. Learned Scripts
  194.          [98]8.12. Pattern Matching
  195.          [99]8.13. Dates and Times
  196.          [100]8.14. Trapping Keyboard Interruption
  197.     [101]9. S-EXPRESSIONS
  198.          [102]9.1. What is an S-Expression?
  199.          [103]9.2. Integer and Floating-Point-Arithmetic
  200.          [104]9.3. How to Use S-Expressions
  201.          [105]9.4. Summary of Built-in Constants and Operators
  202.          [106]9.5. Variables
  203.          [107]9.6. Assignments and Scope
  204.          [108]9.7. Conditional Expressions
  205.          [109]9.8. Extensibility
  206.          [110]9.9. Examples
  207.          [111]9.10. Differences from Algebraic Notation
  208.          [112]9.11.Differences from Lisp
  209.     [113]10. FILE TRANSFER
  210.     [114]11. MODEMS AND DIALING
  211.     [115]12. TERMINAL CONNECTION
  212.     [116]13. CHARACTER SETS
  213.     [117]14. DIALOUT FROM TELNET TERMINAL SERVERS
  214.     [118]15. COPING WITH BROKEN KERMIT PARTNERS
  215.     [119]16. NEW COMMAND-LINE OPTIONS
  216.     [120]17. LOGS
  217.    
  218.    [ [121]Top ] [ [122]C-Kermit Home ] [ [123]Kermit Home ]
  219.   __________________________________________________________________________
  220.  
  221. 0. WHAT'S NEW
  222.  
  223.    The Initialization and Customization Files
  224.           C-Kermit 8.0 now supports specification of the initialization
  225.           file name (path) in an environment variable, CKERMIT_INI. It
  226.           also relies far less than before on the initialization for
  227.           functioning. See [124]Section 5 of the Unix C-Kermit
  228.           [125]installation instructions for details. As of version
  229.           8.0.201, C-Kermit also executes your customization file (if you
  230.           have one) even if the initialization file was not found.
  231.           Previously, the customization file was executed by a TAKE
  232.           command in the initialization file (and it still is, if an
  233.           initialization is found).
  234.           
  235.    Incompatible Changes
  236.           As always, we do our best to avoid changes that break existing
  237.           scripts. However, C-Kermit 8.0 does include a rather pervasive
  238.           syntax change that might alter the behavior of scripts that
  239.           depend on the previous behavior. As described in [126]Section
  240.           5, C-Kermit now accepts doublequotes in most contexts where you
  241.           previously had to use braces to group multiple words into a
  242.           single field, or to force inclusion of leading or trailing
  243.           blanks. Most noticeably, in C-Kermit 7.0 and earlier:
  244.           
  245.   echo {this is a string}
  246.  
  247.           would print:
  248.           
  249.   this is a string
  250.  
  251.           whereas:
  252.           
  253.   echo "this is a string"
  254.  
  255.           printed:
  256.           
  257.   "this is a string"
  258.  
  259.           In C-Kermit 8.0, both print:
  260.           
  261.   this is a string
  262.  
  263.           To force the doublequotes to be treated as part of the string,
  264.           use either of the following forms:
  265.           
  266.   echo {"this is a string"}
  267.   echo ""this is a string""
  268.  
  269.           Similarly, to force braces to be treated as part of the string:
  270.           
  271.   echo "{this is a string}"
  272.   echo {{this is a string}}
  273.  
  274.           Other incompatibilities:
  275.           
  276.          1. Using the SET HOST command to make HTTP connections is no
  277.             longer supported. Instead, use the new HTTP OPEN command,
  278.             described in [127]Section 2.2.
  279.             
  280.    C-Kermit 7.1 Alpha.01 (8 December 2000)
  281.           
  282.      Its major new features are those listed in the [128]Table of
  283.           Contents: the FTP client, file scanning, command parsing and
  284.           scripting improvements, S-Expressions, and support for the
  285.           Telnet Com Port Option, plus wider availability of the
  286.           Kerberos, SSL/TLS, and SRP security options for secure Internet
  287.           connections.
  288.           
  289.    C-Kermit 7.1.199 Alpha.02 (4 January 2001)
  290.           
  291.      C-Kermit now accepts [129]FTP, TELNET, and IKSD URLs as its first
  292.           command-line argument.
  293.           
  294.      Character-set translation added to the FTP client for
  295.           [130]filenames. 
  296.           
  297.      Optional [131]setting of date of incoming files by FTP [M]GET from
  298.           the server date.
  299.           
  300.      [132]FTP CHECK filename added to let FTP client check the existence
  301.           of a file on the server.
  302.           
  303.      [133]FTP GET /NAMELIST:filename added to get list of server
  304.           filenames into a local file.
  305.           
  306.      [134]FTP [M]PUT /SERVER-RENAME:template added to make server rename
  307.           a file as indicated by the template after it has arrived
  308.           completely.
  309.           
  310.      FTP [M]GET /SERVER-RENAME:template added to make server rename a
  311.           file as indicated by the template after it has been sent
  312.           completely.
  313.           
  314.      FTP [135]VDIRECTORY added for getting verbose directory listings
  315.           from TOPS-20.
  316.           
  317.      [136]FTP TYPE TENEX added for transferring 8-bit binary files with
  318.           PDP-10s.
  319.           
  320.      Added [137]automatic text/binary mode switching for FTP [M]GET,
  321.           based on filename patterns (e.g. *.zip, *.gz, *.exe are binary;
  322.           *.txt, *.c are text).
  323.           
  324.      [138]SET SEND I-PACKETS OFF added for coping with Kermit servers
  325.           that do not support I packets.
  326.           
  327.      A new option was added to [139]\fword() and \fsplit() for parsing
  328.           comma-separated lists that might contain empty elements.
  329.           
  330.      Bug fixes including:
  331.           
  332.           + {} or "" could not be used as expected to represent the empty
  333.             string.
  334.           + ,- on a line by itself in a macro definition caused
  335.             subsequent statements to be skipped.
  336.           + FTP [M]GET didn't work right if path segments were included
  337.             in the filespec.
  338.           + FTP MGET, if interrupted, did not clear its file list.
  339.           + Various problems with FTP PUT /AS-NAME that nobody noticed.
  340.           + Some FTP messages and displays interfered with each other.
  341.           + Parsing of YESTERDAY, TODAY, and TOMORROW in date-time fields
  342.             was broken.
  343.           + Automatic old-to-new dialing directory format conversion was
  344.             broken on VMS.
  345.           + Various source-code portability problems fixed.
  346.             
  347.      Improvement of various HELP and SHOW messages.
  348.           
  349.    C-Kermit 7.1.199 Alpha.04 (1 April 2001)
  350.           
  351.      Big changes:
  352.           
  353.           + Changed default modem type from NONE to GENERIC.
  354.           + Generic dialing now sends no init string at all.
  355.           + Changed default terminal bytesize from 7 to 8.
  356.             
  357.      New features:
  358.           
  359.           + SET SESSION-LOG TIMESTAMPED-TEXT for timestamped session log.
  360.             
  361.      New modem types:
  362.           
  363.           + Conexant modem family
  364.           + Lucent VENUS chipset
  365.           + PCTel V.90 chipset
  366.           + Zoom V.90
  367.           + Zoom V.92
  368.             
  369.      FTP client:
  370.           
  371.           + FTP OPEN /PASSIVE and /ACTIVE switches added.
  372.           + Now works with servers that that don't include path in NLST
  373.             response.
  374.           + Fixed SEND /RECURSIVE not to follow symlinks (UNIX).
  375.           + SET FTP VERBOSE-MODE default is now OFF instead of ON.
  376.             
  377.      Kermit protocol:
  378.           
  379.           + Fixed what I hope is the last "Receive window full" error.
  380.           + SET PREFIXING or SET CONTROL PREFIX now automatically sets
  381.             CLEARCHANNEL OFF.
  382.           + Fixed incorrect report of number of files transferred at end
  383.             of transfer.
  384.           + Fixed SEND /RECURSIVE not to follow symlinks (UNIX).
  385.             
  386.      UNIX:
  387.           
  388.           + HTTP and shadow passwords enabled for SCO 5.0.6.
  389.           + Even with SET FILENAMES CONVERTED, spaces were still accepted
  390.             in incoming filenames; now they are converted to underscores.
  391.           + Added support for compile-time mktemp()/mkstemp() selection.
  392.             
  393.      VMS:
  394.           
  395.           + Session-log format for scripted sessions fixed.
  396.             
  397.      Scripting:
  398.           
  399.           + Fixed \frdir() not to follow symlinks (UNIX).
  400.           + Fixed \fday() not to dump core for dates prior to 17 Mar
  401.             1858.
  402.             
  403.      General:
  404.           
  405.           + "Closing blah..." message upon exit could not be surpressed.
  406.           + Added /PAGE and /NOPAGE to DELETE switches.
  407.           + Added GO response for DELETE /ASK (delete all the rest
  408.             without asking).
  409.           + Added GO response to "more?" prompt (for multi-page screen
  410.             output).
  411.           + Updated HELP texts.
  412.             
  413.    C-Kermit 7.1.199 Beta.01 (10 May 2001)
  414.           
  415.      FTP client verbosity adjustments.
  416.           
  417.      Bug with generic modem dialing pausing several secs fixed.
  418.           
  419.      SET HOST /USER:, SET LOGIN USERID, etc, fixed when given no user ID.
  420.           
  421.      A couple \v(dm_blah) dial modifier variables added.
  422.           
  423.      "--version" command-line switch added.
  424.           
  425.      Fixed NetBSD serial-port DTR handling.
  426.           
  427.      Lots of syntax cleanups for Flexelint and gcc -Wall.
  428.           
  429.      Fixed modem-type aliases to not take precedence over real names.
  430.           
  431.      Fixed funny treatment of doublequotes by ECHO command.
  432.           
  433.      Enabled SET SESSION-LOG for VMS and other non-UNIX platorms.
  434.           
  435.      Fixed changing direction in command history buffer.
  436.           
  437.      Fixed handling of IKSD URLs.
  438.           
  439.      Made sure DELETE prints a message if it got any errors.
  440.           
  441.    C-Kermit 8.0.200 Beta.02 (28 June 2001)
  442.           
  443.      Major version number increased from 7 to 8.
  444.           
  445.      [140]SSH command.
  446.           
  447.      More-consistent Kermit protocol defaults.
  448.           
  449.      CONNECT idle timeout and action selection.
  450.           
  451.      CONNECT status variable.
  452.           
  453.      A way to allocate more space for filename lists.
  454.           
  455.      Pseudoterminal handler fixed for late-model Linuxes.
  456.           
  457.      Command-line option -dd for timestamped debug log.
  458.           
  459.      Download directory now works for external protocols too.
  460.           
  461.      GREP /COUNT:variable.
  462.           
  463.      SET ATTRIBUTE RECORD-FORMAT { OFF, ON }.
  464.           
  465.      Bug fixes.
  466.           
  467.    C-Kermit 8.0.200 Beta.03 (9 Sep 2001)
  468.           
  469.      [141]HTTP 1.1 connections and scripting
  470.           
  471.      [142]ON_CTRLC macro for trapping Ctrl-C in scripts
  472.           
  473.      [143]Date-time parsing improvements, timezones, comparison,
  474.           arithmetic
  475.           
  476.      [144]Pattern-matching improvements
  477.           
  478.      FTP improvements
  479.           
  480.      SET EXIT HANGUP { ON, OFF }
  481.           
  482.      SET FILE EOF { CTRL-Z, LENGTH }
  483.           
  484.      ASK[Q] /TIMEOUT
  485.           
  486.      Bug fixes
  487.           
  488.      New platforms
  489.           
  490.    C-Kermit 8.0.200 Beta.04 (16 Nov 2001)
  491.           
  492.      [145]New Unix man page
  493.           
  494.      [146]New Unix installation instructions
  495.           
  496.      SET TELOPT policies are now enforced on non-Telnet ports if the
  497.           server begins Telnet negotiations.
  498.           
  499.      SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT }.
  500.           
  501.      UUCP lockfile creation race condition fixed.
  502.           
  503.      Dialout, modem signals, hangup, hardware flow control, etc, tested
  504.           extensively on many platforms, numerous problems fixed.
  505.           
  506.      Improved hints when dialing fails.
  507.           
  508.      SET STOP-BITS 2 can now be given without SET FLOW HARDWARE.
  509.           
  510.      Major improvements in RFC 2217 Telnet Com-Port Control.
  511.           
  512.      Improved ability to REDIAL a modem server port.
  513.           
  514.      kermit -h now shows the command name in the usage usage string.
  515.           
  516.      kermit -h now shows ALL command-line options.
  517.           
  518.      kermit -s blah, where blah is a symlink, now works.
  519.           
  520.      --noperms command-line option = SET ATTRIBUTE PERMISSIONS OFF.
  521.           
  522.      HTTP and HTTPS URLs now supported on the command line.
  523.           
  524.      An http command-line personality is now available.
  525.           
  526.      Initialization file streamlined to load faster, anachronisms
  527.           removed.
  528.           
  529.      Updated NEWS, INTRO, HELP text, SHOW commands. In particular, see
  530.           SHOW COMM, HELP SET LINE, HELP WAIT.
  531.           
  532.      Date/time arithmetic routines converted from floating-point to
  533.           integer arithmetic (internally) for greater accuracy and
  534.           portability.
  535.           
  536.      Quoted strings containing commas no longer break macro execution.
  537.           
  538.      Dynamic Kermit file-transfer timeouts are now much more aggressive.
  539.           
  540.      New "hot keys" to turn debug.log on/off during file transfer.
  541.           
  542.      Improved hints when file transfer fails.
  543.           
  544.      FTP CD orientation messages are now printed.
  545.           
  546.      -R now accepted on the FTP command line to request Recursion.
  547.           
  548.      -m allows Active or Passive mode to be chosen on the FTP command
  549.           line.
  550.           
  551.      -dd on the FTP command line creates a timestamped debug.log.
  552.           
  553.      FTP command-line security options filled in.
  554.           
  555.      Improved automatic text/binary mode switching for MGET.
  556.           
  557.      Removed spurious error messages that sometimes occur during MGET.
  558.           
  559.      DIRECTORY, GREP, TYPE, HEAD, and TAIL now have a /OUTPUT:file
  560.           option.
  561.           
  562.      TYPE /NUMBER adds line numbers.
  563.           
  564.      CAT = TYPE /NOPAGE; MORE = TYPE /PAGE.
  565.           
  566.      GETOK ?-help fixed.
  567.           
  568.      \v(timestamp) (= "\v(ndate) \v(time)")
  569.           
  570.      \v(hour) (hour of the day, 0-23)
  571.           
  572.      \funix2dospath() converts a UNIX path (/) to a DOS one (\).
  573.           
  574.      \fdos2unixpath() converts a DOS (Windows, OS/2) path to a UNIX one.
  575.           
  576.      \fkeywordval() parses name=value pair, allows macro keyword
  577.           parameters.
  578.           
  579.      We now make every attempt to not write passwords to the debug.log.
  580.           
  581.      New Certficate Authority certificates file, includes the Kermit
  582.           Project at Columbia University so you can access our IKSD
  583.           securely.
  584.           
  585.      Secure targets improved and better documented in Unix makefile.
  586.           
  587.      All Linux (libc and glibc) builds consolidated under "make linux".
  588.           
  589.      HP-UX makefile targets now have consistent names.
  590.           
  591.      New aix50 and aix51 targets added.
  592.           
  593.    C-Kermit 8.0.200 Final (12 Dec 2001)
  594.           
  595.      Remote/local-mode confusion on some platforms introduced in Beta.04,
  596.           fixed.
  597.           
  598.      Many of the makefile targets adjusted, new ones added.
  599.           
  600.      New "make install" target should please most people.
  601.           
  602.      New command: SHOW IKSD.
  603.           
  604.      FTP over TLS.
  605.           
  606.      Last-minute touchups to text messages, HELP text, etc.
  607.           
  608.      Enable modem-signal reading for SCO OSR5 and Unixware 7.
  609.           
  610.      Special superfast TRANSMIT /BINARY /NOECHO /NOWAIT mode added.
  611.           
  612.      Fixed PBX dialing in unmarked-area-code case.
  613.           
  614.      Improved SHOW COMMUNICATIONS tells lockfile directory, typical
  615.           dialout device name.
  616.           
  617.      Some FTP OPEN command parsing problems fixed.
  618.           
  619.      Some errors in date arithmetic fixed.
  620.           
  621.      New command: SET TERMINAL AUTODOWNLOAD { ..., ERROR { STOP, CONTINUE
  622.           } }
  623.           
  624.      New command: HELP FIREWALL.
  625.           
  626.      SET MODEM HANGUP-METHOD DTR added as synomym for RS232-SIGNAL
  627.           
  628.      Support for secure URL protocols added: telnets:, ftps:, https:.
  629.           
  630.    C-Kermit 8.0.201 (8 Feb 2002)
  631.           
  632.      Installability as an [147]SSH v2 Subsystem.
  633.           
  634.      [148]SET LOCUS command.
  635.           
  636.      [149]L-versions of CD, DIR, DELETE, MKDIR, etc, to force local
  637.           execution.
  638.           
  639.      [150]USER and ACCOUNT added as synonyms for FTP USER and FTP
  640.           ACCOUNT.
  641.           
  642.      [151]SHOW VARIABLES now accepts a list of variables.
  643.           
  644.      Rudimentary support for [152]Caller ID when receiving phone calls.
  645.           
  646.      Up/Down [153]Arrow-key navigation of command history buffer.
  647.           
  648.      [154]Automatic execution of customization file if init file is
  649.           missing.
  650.           
  651.    [ [155]Top ] [ [156]Contents ] [ [157]C-Kermit Home ] [ [158]Kermit
  652.    Home ]
  653.   __________________________________________________________________________
  654.  
  655. 1. FIXES SINCE VERSION 7.0.196 First, the changes from 7.0.196 to 7.0.197...
  656. Source and makefile tweaks to get successful builds on platforms that were not
  657. available in time for the 7.0 release:
  658.  
  659.      * 4.2BSD
  660.      * 4.3BSD
  661.      * AIX 4.3
  662.      * AT&T 3B2 and 3B20
  663.      * BeOS 4.5
  664.      * CLIX
  665.      * Interactive UNIX System V/386 R3.2 V4.1.1
  666.      * OS-9/68000
  667.      * OSF/1 1.3.
  668.      * PS/2 AIX 1.2.1
  669.      * SCO OSR5.0.x
  670.      * SCO Xenix 2.3.4
  671.      * SINIX 5.41/Intel
  672.      * Stratus FTX
  673.      * Stratus VOS
  674.      * SunOS 4.1 with X.25
  675.      * Ultrix 4.2
  676.      * Unixware 2.0
  677.        
  678.    There were no functional changes from 196 to 197.
  679.    
  680.    Fixes applied after C-Kermit 7.0.197 was released:
  681.    
  682.    Source code: Big flexelint and "gcc -Wall" audit and cleanup.
  683.    
  684.    Configuration:
  685.      * Solaris RTS/CTS (hardware flow control) didn't work.
  686.      * BSDI RTS/CTS worked only in one direction.
  687.      * FreeBSD 4.0 with ncurses 5.0 broke interactive command parsing.
  688.      * QNX-32 build lacked -DBIGBUFOK so couldn't execute big macros.
  689.        
  690.    Connections:
  691.      * SET HOST /PTY didn't work on some platforms.
  692.      * Broken SET HOST /USER:xxx /PASSWORD:yyy /ACCOUNT:zzz switches
  693.        fixed.
  694.      * Transparent printing was broken in Unix.
  695.      * ANSWER 0 (wait forever) didn't work.
  696.      * Some problems in Multitech modem command strings.
  697.      * Spurious "?Sorry, can't condition console terminal" errors.
  698.      * Disabling modem command strings by setting them to nothing broke
  699.        dialing.
  700.      * SET DIAL TIMEOUT value was usually ignored.
  701.      * SET DIAL METHOD PULSE didn't work.
  702.      * Certain modem commands, if changed, not refreshed if modem type
  703.        changed.
  704.      * SET SESSION-LOG command was missing from VMS.
  705.      * VMS session log format fixed for scripts.
  706.      * HANGUP by dropping DTR didn't work in NetBSD.
  707.      * SET FLOW /AUTO versus SET FLOW confusion fixed.
  708.      * Spurious secondary Solaris lockfile removed.
  709.      * SCO OSR5 DTR On/Off hangup.
  710.      * UUCP lockfile race condition.
  711.        
  712.    Commands and scripts:
  713.      * Missing CAUTIOUS and FAST commands restored.
  714.      * Broken PTY command in late-model Linuxes fixed (API changed).
  715.      * Fixed off-by-one error in command recall when switching direction.
  716.      * Fixed recall of commands that contain '?'.
  717.      * COPY /SWAP-BYTES didn't work on some architectures.
  718.      * Various combinations of COPY switches didn't work.
  719.      * Various problems with COPY or RENAME with a directory name as
  720.        target.
  721.      * SHIFT didn't decrement \v(argc) if used within IF, ELSE, or SWITCH
  722.        block.
  723.      * SHIFT didn't affect the \%* variable.
  724.      * Divide by zero improperly handled in some \function()s.
  725.      * Problems with RETURN from right-recursive functions.
  726.      * FSEEK /LINE \%c LAST didn't work if already at end.
  727.      * Some buffer vulnerabilities and potential memory leaks were
  728.        discovered and fixed.
  729.      * \frdirectory() fixed not to follow symbolic links.
  730.      * SET EXIT WARNING OFF fixed to work when EXIT given in a script.
  731.      * Missing DELETE and MKDIR error message fixed.
  732.      * \fday() core dump for ancient dates fixed.
  733.        
  734.    File transfer:
  735.      * SEND /COMMAND was broken.
  736.      * CRECEIVE was broken (but RECEIVE /COMMAND was OK).
  737.      * Quoting wildcard chars in filenames didn't work.
  738.      * Problems canceling streaming file transfers with X or Z.
  739.      * Problems shifting between streaming and windowing file transfer.
  740.      * Non-FULL file-transfer displays erroneously said STREAMING when
  741.        not.
  742.      * An active SEND-LIST prevented GET from working.
  743.      * SET SERVER GET-PATH interpretation of relative names like "." was
  744.        wrong.
  745.      * The MAIL command was broken.
  746.      * "kermit -s *" might have skipped some files.
  747.      * Transaction log entries were not made for external protocol
  748.        transfers.
  749.      * File count report fixed to show number of files actually
  750.        transferred.
  751.      * Fixed filename conversion to convert spaces to underscores.
  752.      * Made SET PREFIXING / SET CONTROL PREFIX also adjust CLEARCHANNEL.
  753.      * More "Receive window full" errors fixed.
  754.      * Broken terminal buffering after curses display in Solaris fixed.
  755.      * SET FILE INCOMPLETE DISCARD did not work in all cases.
  756.      * Packet log changed to reformat the start-of-packet character
  757.        printably.
  758.      * Dynamic timeouts could grow ridiculously large.
  759.        
  760.    Character sets:
  761.      * Hebrew-7 translations missed the letter Tav.
  762.      * C1 area of CP1252 was ignored.
  763.      * SET TRANSFER CHARACTER-SET TRANSPARENT could give garbage
  764.        translations.
  765.      * TRANSLATE might not work on Little Endian architectures.
  766.      * Insufficient range checking in certain TRANSLATE operations.
  767.        
  768.    The following bugs in C-Kermit 8.0.200 were fixed in 8.0.201:
  769.    
  770.      * An obscure path through the code could cause the Unix version of
  771.        C-Kermit to dump core during its startup sequence. This happened
  772.        to only one person, but now it's fixed.
  773.      * When C-Kermit 8.0 is in Kermit server mode and the client says
  774.        "get blah", where blah (on the server) is a symlink rather than a
  775.        real file, the server unreasonably refused to send the linked-to
  776.        file.
  777.      * When C-Kermit is an FTP client and says "get foo/bar" (i.e. a
  778.        filename that includes one or more path segments), it failed to
  779.        accept the incoming file (this happened only with GET, not MGET).
  780.      * Array references should be case insensitive but only lowercase
  781.        array letters were accepted.
  782.      * SHOW VARIABLES dumped core on \v(sexpression) and \v(svalue).
  783.      * Spurious refusals of remote directory listings if the remote
  784.        server's date was set in the past.
  785.      * In AIX, and maybe elsewhere too, Kermit's COPY command always
  786.        failed with "Source and destination are the same file" when the
  787.        destination file didn't exist.
  788.      * The VMS version of C-Kermit did not work in Batch or when SPAWN'd.
  789.        To compound the problem, it also pretty much ignored the -B and -z
  790.        command-line options, whose purpose is to work around such
  791.        problems.
  792.      * C-Kermit 8.0 could not be built on IRIX 5.x.
  793.      * The C-Kermit 8.0 build for QNX6 said it was an "(unknown
  794.        version)".
  795.        
  796.    [ [159]Top ] [ [160]Contents ] [ [161]C-Kermit Home ] [ [162]Kermit
  797.    Home ]
  798.   __________________________________________________________________________
  799.  
  800. 2. SSH AND HTTP
  801.  
  802.   2.1. SSH Connections
  803.   
  804.    On most UNIX platforms, C-Kermit can make SSH (Secure SHell)
  805.    connection by running the external SSH command or program through its
  806.    pseudoterminal interface. The command is:
  807.    
  808.    SSH text
  809.           Tells Kermit to start the external SSH client, passing the
  810.           given text to it on the command line. Normally the text is just
  811.           the hostname, but it can be anything else that is acceptable to
  812.           the ssh client. If the command succeeds, the connection is made
  813.           and Kermit automatically enters CONNECT (terminal) mode. You
  814.           can use the SSH command to make a connection to any host that
  815.           has an SSH server.
  816.           
  817.    Kermit's SSH command gives you all the features of Kermit on an SSH
  818.    connection: command language, file transfer, character-set
  819.    translation, scripting, and all the rest. By default, C-Kermit invokes
  820.    SSH with "-e none", which disables the ssh escape character and makes
  821.    the connection transparent for purposes of file transfer. You can,
  822.    however, change the SSH invocation to whatever else you might need (an
  823.    explicit path, additional command-line arguments, etc) with:
  824.    
  825.    SET SSH COMMAND text
  826.           Specifies the system command that Kermit's SSH command should
  827.           use to invoke the external SSH client. Use this command to
  828.           supply a specific path or alternative name, or to include
  829.           different or more command-line options.
  830.           
  831.    In most cases, these connections work quite well. They can be scripted
  832.    like any other connection, and file transfer goes as fast as, or
  833.    faster than, on a regular Telnet connection. In some cases, however,
  834.    the underlying pseudoterminal driver is a limiting factor, resulting
  835.    in slow or failed file transfers. Sometimes you can work around such
  836.    problems by reducing the Kermit packet length. Note that Kermit does
  837.    not consider SSH connections to be reliable, so it does not offer to
  838.    use streaming in Kermit protocol transfers (but you can force it with
  839.    SET RELIABLE or SET STREAMING if you wish).
  840.    
  841.    The SSH command is like the TELNET command: it enters CONNECT mode
  842.    automatically when the connection is made. Therefore, to script an SSH
  843.    connection, use:
  844.    
  845.   set host /pty ssh -e none [ other-options ] host
  846.   if fail ...
  847.  
  848.    to make the connection.
  849.    
  850.    Here's a sequence that can be used to make a connection to a given
  851.    host using Telnet if the host accepts it, otherwise SSH:
  852.    
  853.   if not defined \%1 exit 1 Usage: \%0 host
  854.   set quiet on
  855.   set host \%1 23 /telnet
  856.   if fail {
  857.       set host /pty ssh -l \m(user) -e none \%1
  858.       if fail exit 1 \%1: Telnet and SSH both fail
  859.       echo SSH connection to \%1 successful
  860.   } else {
  861.       echo Telnet connection to \%1 successful
  862.   }
  863.  
  864.    In SSH v2, it is possible to make an SSH connection direct to a Kermit
  865.    server system if the host administrator has configured the SSH server
  866.    to allow this; [163]CLICK HERE for details.
  867.    
  868.    Since Kermit uses external ssh client software, and since there are
  869.    different ssh clients (and different releases of each one), the exact
  870.    command to be used to make an SSH/Kermit connection can vary. Here is
  871.    the command for the OpenSSH 3.0.2p1 client:
  872.    
  873. set host /pipe ssh -e none [ -l username ] -T -s hostname kermit
  874.  
  875.    Example:
  876.    
  877. set host /pipe ssh -e none -l olga -T -s hq.xyzcorp.com kermit
  878.  
  879.    The SSH client might or might not prompt you for a password or other
  880.    information before it makes the connection; this depends on your SSH
  881.    configuration (your public and private keys, your authorized hosts
  882.    file, etc). Here's a brief synopsis of the OpenSSH client command
  883.    syntax ("man ssh" for details):
  884.    
  885.    -e none
  886.           This tells the SSH client to use no escape character. Since we
  887.           will be transferring files across the connection, we don't want
  888.           the connection to suddenly block because some character in the
  889.           data.
  890.           
  891.    -l username
  892.           This is the username on the remote host. You can omit the -l
  893.           option and its argument if your local and remote usernames are
  894.           the same. If they are different, you must supply the remote
  895.           username.
  896.           
  897.    -T
  898.           This tells the SSH client to tell the SSH server not to
  899.           allocate a pseudoterminal. We are not making a terminal
  900.           connection, we don't need a terminal, and in fact if a terminal
  901.           were allocated on the remote end, the connection would not
  902.           work.
  903.           
  904.    -s ... kermit
  905.           This tells the SSH client to tell the SSH server to start the
  906.           specified subsystem ("kermit") once the connection is made. The
  907.           subsystem name comes after the hostname.
  908.           
  909.    hostname
  910.           The IP host name or address of the desired host.
  911.           
  912.    You might want to include other or additional ssh command-line
  913.    options; "man ssh" explains what they are. Here are some examples for
  914.    the OpenSSH 3.0.2p1 client:
  915.    
  916.    -oClearAllForwardings yes
  917.           
  918.    -oForwardAgent no
  919.           
  920.    -oForwardX11 no
  921.           
  922.    -oFallbackToRsh no
  923.           These ensure that a secure connection is used and that the
  924.           connection used for file transfer is not also used for
  925.           forwarding other things that might be specified in the
  926.           ssh_config file.
  927.           
  928.    -oProtocol 2
  929.           (i.e. SSH v2) Ensures that the negotiated protocol supports
  930.           subsystems.
  931.           
  932.    Once you have an SSH connection to a Kermit server, it's just like any
  933.    other connection to a Kermit server (and very similar to a connection
  934.    to an FTP server). You give the client file transfer and management
  935.    commands for the server, and the server executes them. Of course you
  936.    can also give the client any other commands you wish.
  937.    
  938.    [ [164]SSH Kermit Server Subsystem ] [ [165]Kermit 95 Built-in SSH
  939.    Client ]
  940.      _________________________________________________________________
  941.    
  942.   2.2. HTTP Connections
  943.   
  944.    Hypertext Transfer Protocol, or HTTP, is the application protocol of
  945.    the World Wide Web (WWW), used between Web browsers (clients) and Web
  946.    servers. It allows a client to get files from websites, upload files
  947.    to websites, delete files from websites, get information about website
  948.    directories and files, and interact with server-side CGI scripts.
  949.    C-Kermit includes an HTTP client capable of both clear-text and secure
  950.    HTTP connections, that can do all these tasks and can be automated
  951.    through the Kermit scripting language.
  952.    
  953.    Although C-Kermit 7.0 could make HTTP connections to Web servers, it
  954.    could do so only when no other connection was open, and the procedure
  955.    was somewhat awkward. C-Kermit 8.0 improves matters by:
  956.    
  957.      * Allowing an HTTP connection to be open at the same time as a
  958.        regular SET LINE or SET HOST connection, and also at the same time
  959.        as an FTP connection ([166]Section 3);
  960.      * Upgrading the HTTP protocol level from 1.0 to 1.1, thus allowing
  961.        for persistent connections, in which a series of commands can be
  962.        sent on the same connection, rather than only one as in HTTP 1.0
  963.        (and C-Kermit 7.0);
  964.      * Providing for "one-shot" URL-driven HTTP operations such as GET or
  965.        PUT.
  966.      * Providing a distinct HTTP command-line personality.
  967.        
  968.    Persistent HTTP connections are managed with the following commands:
  969.    
  970.    HTTP [ switches ] OPEN [ security-options ] host-or-url [ port ] 
  971.           Opens a persistent connection to the specified host (IP host
  972.           name or address) on the specified port. If any switches
  973.           (options, listed in the next section) are included, their
  974.           values are saved and used for all subsequent HTTP action
  975.           commands on the same connection. If no port is specified, HTTP
  976.           (80) is used. A Uniform Resource Locator (URL, [167]RFC 1738)
  977.           can be given instead of a hostname (or address) and port (but
  978.           the URL can not include a directory/file path). The security
  979.           options are explained [168]below. The HTTP OPEN command
  980.           replaces the C-Kermit 7.0 SET HOST hostname HTTP command, which
  981.           no longer works with HTTP GET and related commands.
  982.           
  983.    HTTP CLOSE
  984.           Closes any open HTTP connection and clears any saved switch
  985.           values.
  986.           
  987.    A URL starts with a protocol name, which must be http or https in this
  988.    case; optionally includes a username and password; and must contain a
  989.    host name or address:
  990.    
  991.   protocol://[user[.password]]@host[:port][URI]
  992.  
  993.    HTTP is Hypertext Transfer Protocol. HTTPS is the secure (SSL/TLS)
  994.    version of HTTP. The TCP service port is derived from the protocol
  995.    prefix (so normally the ":port" field is omitted). Thus the URL
  996.    protocol name specifies a default TCP service port and the URL user
  997.    and password fields can take the place of the /USER and /PASSWORD
  998.    switches ([169]Section 2.2.1). The optional URI is a "compact string
  999.    of characters for identifying an abstract or physical resource"
  1000.    ([170]RFC 2396), such as a file. It must begin with a slash (/); if
  1001.    the URI is omitted, "/" is supplied. Examples:
  1002.    
  1003.    http open http://www.columbia.edu/
  1004.           Equivalent to http open www.columbia.edu or http open
  1005.           www.columbia.edu http.
  1006.           
  1007.    http open https://olga.secret@www1.xyzcorp.com/
  1008.           Equivalent to http /user:olga /pass:secret open
  1009.           www1.xyzcorp.com https.
  1010.           
  1011.    Persistence is accomplished unilaterally by C-Kermit 8.0. An HTTP 1.0
  1012.    server closes the connection after each action. Although HTTP 1.1
  1013.    allows multiple actions on the same connection, an HTTP 1.1 server
  1014.    tends to close the connection if it is idle for more than a few
  1015.    seconds, to defend itself against denial-of-service attacks. But when
  1016.    you use Kermit's HTTP OPEN command to create a connection, Kermit
  1017.    reopens it automatically (if necessary) for each HTTP action until you
  1018.    close it with HTTP CLOSE, regardless of the server's HTTP protocol
  1019.    version, or how many times it closes the connection.
  1020.    
  1021.    Firewalls can be negotiated through proxies with the following
  1022.    commands:
  1023.    
  1024.    SET TCP HTTP-PROXY [ host[:port] ]
  1025.           If a host (by hostname or IP address) is specified, Kermit uses
  1026.           it as a proxy server when attempting outgoing TCP connections
  1027.           -- not only HTTP connections, but all TCP/IP connections,
  1028.           Telnet and FTP included. This allows Kermit to adapt to the
  1029.           HTTP firewall penetration method (as opposed to other methods
  1030.           such as SOCKS4). If no hostname or ip-address is specified, any
  1031.           previously specified Proxy server is removed. If no port number
  1032.           is specified, the "http" service is used. This command must be
  1033.           given before the HTTP OPEN command if a proxy is to be used or
  1034.           canceled.
  1035.           
  1036.    HTTP [ switches ] CONNECT host[:port]
  1037.           Instructs the HTTP server to act as a proxy, establishing a
  1038.           connection to the specified host (IP hostname or address) on
  1039.           the given port (80 = HTTP by default) and to redirect all data
  1040.           transmitted between Kermit and itself to the given host for the
  1041.           life of the connection. This command is to be used only for
  1042.           debugging HTTP proxy connections. If a proxy connection is
  1043.           required, instruct Kermit to use the proxy with the SET TCP
  1044.           HTTP-PROXY command.
  1045.           
  1046.     2.2.1. HTTP Command Switches
  1047.     
  1048.    HTTP switches, like all other switches, are optional. When HTTP
  1049.    switches are included with the HTTP OPEN command, they apply
  1050.    automatically to this and all subsequent HTTP actions (GET, PUT, ...)
  1051.    on the same connection until an HTTP CLOSE command is given. So if you
  1052.    include switches (or the equivalent URL fields, such as user and
  1053.    password) in the HTTP OPEN command, you can omit them from subsequent
  1054.    commands on the same connection. If the connection has closed since
  1055.    your last command, it is automatically reopened with the same options.
  1056.    
  1057.    If you include switches with an HTTP action command (such as GET or
  1058.    PUT), they apply only to that command.
  1059.    
  1060.    /USER:name
  1061.           To be used in case a page requires a username for access. The
  1062.           username is sent with page requests. If it is given with the
  1063.           OPEN command it is saved until needed. If a username is
  1064.           included in a URL, it overrides the username given in the
  1065.           switch. CAUTION: Username and password (and all other
  1066.           information, including credit card numbers and other material
  1067.           that you might prefer to protect from public view) are sent
  1068.           across the network in clear text on regular HTTP connections,
  1069.           but authentication is performed securely on HTTPS connections.
  1070.           
  1071.    /PASSWORD:text
  1072.           To be used in case a web page requires a password for access.
  1073.           The password is sent with page requests. If it is given with
  1074.           the OPEN command it is saved until needed. If a password is
  1075.           given in a URL, it overrides the one given here. CAUTION: (same
  1076.           as for /USER:).
  1077.           
  1078.    /AGENT:user-agent
  1079.           Identifies the client to the server. Overrides the default
  1080.           agent string, which is "C-Kermit" (for C-Kermit) or "Kermit-95"
  1081.           (for Kermit 95).
  1082.           
  1083.    /ARRAY:array-designator
  1084.           Tells Kermit to store the response headers in the given array,
  1085.           one line per element. The array need not be declared in
  1086.           advance. Example: /array:&a.
  1087.           
  1088.    /TOSCREEN
  1089.           Tells Kermit to display any response text on the screen. It
  1090.           applies independently of the output file specification; thus it
  1091.           is possible to have the server response go to the screen, a
  1092.           file, both, or neither.
  1093.           
  1094.    /HEADER:header-item(s)
  1095.           Used for specifying any optional headers to be sent with HTTP
  1096.           requests.
  1097.           
  1098.   /HEADER:tag:value
  1099.  
  1100.           To send more than one header, use braces for grouping:
  1101.           
  1102.   /HEADER:{{tag:value}{tag:value}...}
  1103.  
  1104.           For a list of valid tags and value formats see [171]RFC 2616,
  1105.           "Hypertext Transfer Protocol -- HTTP/1.1". A maximum of eight
  1106.           headers may be specified.
  1107.           
  1108.     2.2.2. HTTP Action Commands
  1109.     
  1110.    HTTP actions can occur within a persistent connection, or they can be
  1111.    self-contained ("connectionless"). A persistent HTTP connection begins
  1112.    with an HTTP OPEN command, followed by zero or more HTTP action
  1113.    commands, and is terminated with an HTTP CLOSE command:
  1114.    
  1115.   http open www.columbia.edu
  1116.   if failure stop 1 HTTP OPEN failed: \v(http_message)
  1117.   http get kermit/index.html
  1118.   if failure stop 1 HTTP GET failed: \v(http_message)
  1119.   (more actions possible here...)
  1120.   http close
  1121.  
  1122.    A self-contained HTTP action occurs when a URL is given instead of a
  1123.    remote file name to an HTTP action command. In this case, Kermit makes
  1124.    the HTTP connection, takes the action, and then closes the connection.
  1125.    If an HTTP connection was already open, it is closed silently and
  1126.    automatically.
  1127.    
  1128.   http get http://www.columbia.edu/kermit/index.html
  1129.  
  1130.    Kermit's HTTP action commands are as follows. Switches may be included
  1131.    with any of these to override switch (or default) values given in the
  1132.    HTTP OPEN command.
  1133.    
  1134.    HTTP [ switches ] GET remote-filename [ local-filename ]
  1135.           Retrieves the named file from the server specified in the most
  1136.           recent HTTP OPEN command for which a corresponding HTTP CLOSE
  1137.           command has not been given. The filename may not include
  1138.           wildcards (HTTP protocol does not support them). If no HTTP
  1139.           OPEN command is in effect, this form of the HTTP GET command
  1140.           fails. The default local filename is the same as the remote
  1141.           name, but with any pathname stripped. For example, the command
  1142.           http get kermit/index.html stores the file in the current local
  1143.           directory as index.html. If the /HEADERS: switch is included,
  1144.           information about the file is also stored in the specified
  1145.           array (explained in [172]Section 2.2.3). All files are
  1146.           transferred in binary mode. HTTP does not provide for
  1147.           record-format or character-set conversion.
  1148.           
  1149.    HTTP [ switches ] GET url [ local-filename ]
  1150.           When HTTP GET is given a URL rather than a filename, Kermit
  1151.           opens a connection to the designated server (closing any
  1152.           previously open HTTP connection), gets the file, and then
  1153.           closes the connection. If the URL does not include a filename,
  1154.           index.html is supplied. This is the self-contained one-step
  1155.           "connectionless" method for getting a file from a Web server.
  1156.           The data is not interpreted; HTTP GET is like "lynx -source"
  1157.           rather than "lynx -dump".
  1158.           
  1159.    In the remaining HTTP action commands, the distinction between a
  1160.    remote filename and a URL are the same as in the HTTP GET command.
  1161.    
  1162.    HTTP [ switches ] HEAD remote-filename-or-url [ local-filename ]
  1163.           Like GET except without actually getting the file; instead it
  1164.           retrieves only the headers. If the /ARRAY: or /TOSCREEN switch
  1165.           is included, there is no default local output filename but you
  1166.           can still specify one. If neither of these switches is
  1167.           included, the default local filename is the same as the remote
  1168.           filename, but with any path stripped and with ".head" appended.
  1169.           The HEAD command can be used in a script with the /ARRAY:
  1170.           switch to retrieve information about the requested resource to
  1171.           determine whether the resource should actually be retrieved
  1172.           with a subsequent GET request.
  1173.           
  1174.    HTTP [ switches ] INDEX remote-directory-or-url [ local-filename ]
  1175.           Asks the server to send a listing of the files in the given
  1176.           server directory. This command is not supported by most Web
  1177.           servers. Even when it is supported, there is no standard format
  1178.           for the listing.
  1179.           
  1180.    HTTP [ switches ] POST [ /MIME-TYPE:type ] source-file
  1181.           remote-path-or-url [ result-file ]
  1182.           Sends data to a process running on the remote host; the result
  1183.           is usually an HTML file but could be anything. The data to be
  1184.           posted must be read from a local file (the source-file). If a
  1185.           result file is specified, Kermit stores the server's response
  1186.           in it.
  1187.           
  1188.    HTTP [ switches ] PUT [ MIME-TYPE:type ] local-file [
  1189.           remote-file-or-url [ result-file ] ]
  1190.           Uploads a local file to the server. Only the name of a single
  1191.           file can be given; wildcards (and group transfers) are not
  1192.           supported by HTTP protocol. If no remote filename is given, the
  1193.           file is sent with the same name as the local file, but with any
  1194.           pathname stripped.
  1195.           
  1196.    HTTP [ switches ] DELETE remote-file-or-url [ local-result-file ]
  1197.           Asks the server to delete the specified single file. If a
  1198.           result file is specified, it will contain any response data
  1199.           returned by the server.
  1200.           
  1201.    Note the limitations of HTTP protocol compared to (say) FTP or Kermit.
  1202.    There is no command for changing directories, no standard way to get
  1203.    file or directory lists, no way to transfer file groups by using
  1204.    wildcard notation, etc, and therefore no good way to (say) fetch all
  1205.    pages, descend through subdirectories, perform automatic updates, etc.
  1206.    There is no assurrance a connection will stay open and, as noted,
  1207.    there is no provision for data conversion between unlike platforms.
  1208.    The data's MIME headers can be used for postprocessing.
  1209.    
  1210.     2.2.3. HTTP Headers
  1211.     
  1212.    Each HTTP request and response contains a set of name/value pairs
  1213.    called headers. HTTP headers are specified in [173]RFC 2616. For
  1214.    example, an HTTP GET request for /index.html on www.columbia.edu
  1215.    contains the following headers:
  1216.    
  1217.   GET /index.html HTTP/1.1
  1218.   Host: www.columbia.edu:80
  1219.   User-agent: C-Kermit 8.0
  1220.   Authorization: Basic base64-encoded-username-password
  1221.  
  1222.    These might be followed by any others specified with a /HEADERS:
  1223.    switch:
  1224.    
  1225.   Accept: image/gif, image/x-xbitmap, image/jpeg, *.*
  1226.   Accept-Encoding: gzip
  1227.   Accept-Language: en
  1228.   Accept-Charset: iso-8859-1,utf-8
  1229.   Cookie: cookie-data
  1230.  
  1231.    The server sends back a short report about the file prior to sending
  1232.    the file contents. Example:
  1233.    
  1234.   HTTP/1.1 200 OK
  1235.   Date: Fri, 24 Aug 2001 21:09:39 GMT
  1236.   Server: Apache/1.3.4 (Unix)
  1237.   Last-Modified: Mon, 06 Aug 2001 21:16:13 GMT
  1238.   ETag: "1fa137-10d7-3b6f091d"
  1239.   Accept-Ranges: bytes
  1240.   Content-Length: 4311
  1241.   Content-Type: text/html
  1242.  
  1243.    If you want to have this information available to a Kermit script you
  1244.    can use the /ARRAY switch to have Kermit put it in array, one line per
  1245.    array element. Example:
  1246.    
  1247.   set exit warning off
  1248.   http open www.columbia.edu
  1249.   if fail exit 1 Can't reach server
  1250.   http /array:&a get /index.html
  1251.   if fail exit 1 Can't get file
  1252.   echo Header lines: \fdim(&a)
  1253.   for \%i 1 \fdim(&a) 1 {
  1254.       echo \%i. \&a[\%i]
  1255.   }
  1256.  
  1257.    Note that the "Date:" item is the current date and time; the
  1258.    "Last-Modifed:" item is the file's modification date and time. An
  1259.    example showing how to use this information is presented in
  1260.    [174]Section 8.13.7.
  1261.    
  1262.     2.2.4. Secure HTTP Connections
  1263.     
  1264.    SSL/TLS (Secure Sockets Layer / Transport Layer Security) is the
  1265.    protocol used to secure HTTP, SMTP, and other Internet applications.
  1266.    See the [175]C-Kermit Reference Section 5.4 for an introduction to
  1267.    SSL/TLS. To make a secure HTTP connection, you need:
  1268.    
  1269.     1. A secure client (a version of C-Kermit or Kermit 95 with SSL/TLS
  1270.        security built in). Type "check ssl" at the Kermit prompt to make
  1271.        sure you have it.
  1272.     2. A secure server to connect to.
  1273.     3. The CA Root Certificate used to authenticate the server to the
  1274.        client. (see [176]Section 15 of the security reference for an
  1275.        introduction to certificates).
  1276.        
  1277.    And you must make a connection to the secure HTTP port: service name
  1278.    HTTPS, port number 443 (as opposed to service HTTP, port 80). You can
  1279.    also make secure connections to other ports by including the /TLS or
  1280.    /SSL switch with the HTTP OPEN command, if the host supports SSL/TLS
  1281.    on the given port:
  1282.    
  1283.    The quality of the SSL/TLS connection depends on the cipher suite.
  1284.    There are several possibilities:
  1285.    
  1286.    Anonymous cipher suite:
  1287.           If an anonymous cipher suite is negotiated, the connection is
  1288.           encrypted but there is no authentication. This connection is
  1289.           subject to a Man-In-The-Middle (MITM) attack.
  1290.           
  1291.    X.509 certificate on the server:
  1292.           When you connect to certain secure servers, an X.509
  1293.           certificate is returned. This certificate is issued to a
  1294.           special hostname, something like www1.xyzcorp.com or
  1295.           wwws.xyzcorp.com (rather than the normal www.xyzcorp.com). It
  1296.           is signed by the host's Certificate Authority (CA). If the host
  1297.           certificate is configured on the client, it can be used to
  1298.           verify the certificate received from the server. If the
  1299.           certificate it verified as authentic, a check is made to ensure
  1300.           it has not expired and it was issued to the host you were
  1301.           attempting to connect to. If you had asked to connect to (say)
  1302.           www.xyzcorp.com but were given a certificate for
  1303.           www1.xyzcorp.com, you would be prompted for permission to
  1304.           continue.
  1305.           
  1306.           If the verification succeeded, the connection would be
  1307.           encrypted with one-way (server-to-client) authentication. This
  1308.           connection is not subject to a MITM attack.
  1309.           
  1310.           If a username and password are transmitted over this
  1311.           connection, they are not subject to interception. However, the
  1312.           standard risks associated with passing the password to the host
  1313.           for verification apply; for example, if the host has been
  1314.           compromised, the password will be compromised.
  1315.           
  1316.    X.509 client certificate:
  1317.           If a connection has been established with an X.509 server
  1318.           certificate, the server can ask the client to send a
  1319.           certificate of its own. This certificate must be verified
  1320.           against a CA Root certificate. The certificate itself (or
  1321.           subject info from the certificate) is used to determine the
  1322.           authorization for the client, and if successful, the username
  1323.           and password need not be sent to the server.
  1324.           
  1325.    Kerberos 5:
  1326.           Instead of using X.509 certifcates, Kerberos 5 can be used to
  1327.           perform the authentication and key exchange. In this situation,
  1328.           there is mutual authentication between the client and server.
  1329.           The Kerberos 5 principal is used by the server to look up the
  1330.           appropriate authorization data. There is no need to send
  1331.           username and password.
  1332.           
  1333.    An HTTP connection is made with the HTTP OPEN command:
  1334.    
  1335.    HTTP [ switches ] OPEN [ { /SSL, /TLS } ] host [ port ] 
  1336.           If /SSL or /TLS switches are included (these are synonyms), or
  1337.           if the service is HTTPS or the port is 443, a secure connection
  1338.           is attempted using the current authentication settings; see
  1339.           HELP SET AUTHENTICATION for details ([177]Section 6.2 of the
  1340.           security reference). If the no /SSL or /TLS switch is included
  1341.           but the port is 443 or the service is HTTPS, a secure
  1342.           connection is attempted. If an /SSL or /TLS switch is included
  1343.           but a port is not specified, an SSL/TLS connection is attempted
  1344.           on the default port (80).
  1345.           
  1346.    Certificates are covered in the separate [178]Kermit Security
  1347.    Reference for C-Kermit 8.0. You should let Kermit know to verify
  1348.    certificates with the SET AUTHENTICATION TLS command. For example:
  1349.    
  1350.    SET AUTHENTICATION TLS CRL-DIR directory
  1351.           Specifies a directory that contains certificate revocation
  1352.           files where each file is named by the hash of the certificate
  1353.           that has been revoked.
  1354.           
  1355.    SET AUTHENTICATION TLS CRL-FILE filename
  1356.           Specifies a file that contains a list of certificate
  1357.           revocations.
  1358.           
  1359.    SET AUTHENTICATION TLS VERIFY-DIR directory
  1360.           Specifies a directory that contains root CA certificate files
  1361.           used to verify the certificate chains presented by the peer.
  1362.           Each file is named by a hash of the certificate.
  1363.           
  1364.    SET AUTHENTICATION TLS VERIFY-FILE filename
  1365.           Specifies a file that contains root CA certificates to be used
  1366.           for verifying certificate chains.
  1367.           
  1368.    SET AUTHENTICATION TLS VERIFY OFF
  1369.           Tells Kermit not to require a certificate and accept any
  1370.           certificate that is presented regardless of whether it is
  1371.           valid.
  1372.           
  1373.    There are many other options; see the security document for details.
  1374.    
  1375.    Now suppose you need need to fetch the file denoted by the following
  1376.    URL:
  1377.    
  1378.   https://myuserid:mypassword@wwws.xyzcorp.com/clients/info/secret.html
  1379.  
  1380.    Once you have set up the handling of certificates as desired, you can
  1381.    use the following Kermit commands:
  1382.    
  1383.   http /user:myuserid /password:mypassword open www1.xyzcorp.com https
  1384.   if success {
  1385.       http get /clients/info/secret.html
  1386.       http close
  1387.   }
  1388.  
  1389.    As another example, let's say that you have a web form you need to
  1390.    populate with three fields: red,white and blue.
  1391.    
  1392.   <FORM ACTION="http://www.xyzcorp.com/cgi-bin/form.cgi" METHOD="POST">
  1393.   <INPUT NAME="Red">
  1394.   <INPUT NAME="White">
  1395.   <INPUT NAME="Blue">
  1396.   </FORM>
  1397.  
  1398.    You can handle this with the HTTP POST command. The data to be posted
  1399.    is stored in the local file data.txt.
  1400.    
  1401.   Red=seven stripes&White=six stripes&Blue=fifty stars
  1402.  
  1403.    and the response from the server will be stored into response.txt.
  1404.    
  1405.   http open www.xyzcorp.com http
  1406.   if success {
  1407.     http /array:c post data.txt /cgi-bin/form.cgi response.txt
  1408.     http close
  1409.   }
  1410.  
  1411.    In this scenario, the Common Gateway Interface (CGI) sends a response
  1412.    whether it succeeds or fails in a script-dependent manner. The script
  1413.    can either report success and enclose the response data; or it might
  1414.    send a 302 Found error which indicates that the "Location:" header
  1415.    should be used to determine the URL at which the data can be found.
  1416.    
  1417.     2.2.5. HTTP Variables
  1418.     
  1419.    \v(http_code)
  1420.           The HTTP protocol code number of the most recent server reply,
  1421.           e.g. 404 for "not found".
  1422.           
  1423.    \v(http_connected)
  1424.           1 when an HTTP connection is open, 0 when there is no HTTP
  1425.           connection.
  1426.           
  1427.    \v(http_host)
  1428.           If an HTTP connection is open, the hostname:port, e.g.
  1429.           www.columbia.edu:80; otherwise, empty.
  1430.           
  1431.    \v(http_message)
  1432.           Server error message, if any, from most recent HTTP command.
  1433.           
  1434.    \v(http_security)
  1435.           A list of the security parameters and values for the current
  1436.           connection, if any. Empty if the connection is not to a secure
  1437.           server, or there is no connection.
  1438.           
  1439.    To display all the HTTP variables at once, type SHOW VAR HTTP:
  1440.    
  1441.   C-Kermit> http open www.columbia.edu
  1442.   C-Kermit> http get lkjlkjlkjlkj 
  1443.   C-Kermit> sho var http
  1444.    \v(http_code) = 404
  1445.    \v(http_connected) = 1
  1446.    \v(http_host) = www.columbia.edu:80
  1447.    \v(http_message) = Not Found
  1448.    \v(http_security) = NULL
  1449.   C-Kermit>
  1450.  
  1451.     2.2.6. The HTTP Command-Line Personality
  1452.     
  1453.    If you invoke C-Kermit with the name "http" or "https", you can use a
  1454.    special set of HTTP-specific command-line options. You can do this by
  1455.    creating a symbolic linke "http" or "https" to the C-Kermit 8.0
  1456.    executable, or by having a separate copy of it called "http" or
  1457.    "https". Here's the usage message ("http -h"):
  1458.    
  1459.   Usage: ./http host [ options... ]
  1460.    -h             This message.
  1461.    -d             Debug to debug.log.
  1462.    -S             Stay (issue command prompt when done).
  1463.    -Y             Do not execute Kermit initialization file.
  1464.    -q             Quiet (suppress most messages).
  1465.    -u name        Username.
  1466.    -P password    Password.
  1467.    -g pathname    Get remote pathname.
  1468.    -p pathname    Put remote pathname.
  1469.    -H pathname    Head remote pathname.
  1470.    -l pathname    Local path for -g, -p, and -H.
  1471.    -z opt[=value] Security options...
  1472.       cert=file   Client certificate file
  1473.       certsok     Accept all certificates
  1474.       key=file    Client private key file
  1475.       secure      Use SSL
  1476.       verify=n    0 = none, 1 = peer , 2 = certificate required
  1477.  
  1478.    The "host" argument is the name of a Web host, e.g. www.columbia.edu.
  1479.    The action options are -p, -g, and -H. If you give an action option,
  1480.    Kermit does the action and then exits. If you give a host without an
  1481.    action option, Kermit makes an HTTP connection to the host and then
  1482.    gives you the C-Kermit prompt. Here's a simple example that fetches a
  1483.    publicly readable Web page:
  1484.    
  1485.   http www.columbia.edu -g kermit/index.html
  1486.  
  1487.    If you need to access a website for which a username and password are
  1488.    required, you can supply them on the command line with -u and -P. If
  1489.    you include a username but omit the password, Kermit prompts you for
  1490.    it:
  1491.    
  1492.   http www.columbia.edu -u olga -p kermit/index.html -l index.html
  1493.   Password:
  1494.  
  1495.    Note that when PUT'ing files to websites, you have to supply both the
  1496.    -p (remote pathname) and -l (local path) options.
  1497.    
  1498.    If your version of Kermit is built with SSL/TLS security, you can also
  1499.    use the -z option to make secure HTTP (https) connections.
  1500.    
  1501.    Finally, as noted in [179]Section 16, you can also give a URL instead
  1502.    of a host name and options.
  1503.    
  1504.    [ [180]Top ] [ [181]Contents ] [ [182]C-Kermit Home ] [ [183]Kermit
  1505.    Home ]
  1506.   __________________________________________________________________________
  1507.  
  1508. 3. THE BUILT-IN FTP CLIENT
  1509.  
  1510.    Earlier versions of C-Kermit and K95 included an FTP command, but it
  1511.    simply invoked an external FTP client. Now, by popular demand, Kermit
  1512.    includes its own built-in FTP client that offers the following
  1513.    advantages over traditional FTP clients (and its previous interface to
  1514.    them):
  1515.      * Any of Kermit's built-in [184]security methods can be used to
  1516.        establish and conduct secure FTP sessions with [185]FTP servers
  1517.        that support these methods. (Security modules can be subject to
  1518.        export restrictions.)
  1519.      * Kermit's FTP client uses "passive mode" by default to avoid
  1520.        blockage by firewalls and network address translators.
  1521.      * [186]Character sets can be translated as part of the transfer
  1522.        process even when the FTP server does not support character-set
  1523.        translation, including to/from the new Internet standard
  1524.        international character set, [187]Unicode UTF-8. This includes
  1525.        both the file's name and (for text files only) its contents.
  1526.      * All of C-Kermit's [188]file-selection mechanisms are available:
  1527.        size, date, name patterns and lists, exception lists, etc.
  1528.      * [189]Atomic file movement operations are provided (delete, move,
  1529.        or rename files automatically after successful transfer).
  1530.      * The correct file type, "ascii" (i.e. text) or binary, is chosen
  1531.        automatically for each file (explained in [190]Section 4), and any
  1532.        mixture of text and binary files can be sent in a single
  1533.        operation, even across platforms.
  1534.      * Update mode ("don't bother transferring files that didn't change
  1535.        since last time") and recovery (resumption of an interrupted
  1536.        transfer from the point of failure) are available in both
  1537.        directions.
  1538.      * When uploading files from UNIX to UNIX, the file's permissions can
  1539.        be preserved if desired.
  1540.      * Recursive directory-tree PUTs are supported between any two
  1541.        platforms that have tree-structured file systems. Recursive GETs
  1542.        are supported between like platforms if the server cooperates.
  1543.      * When receiving files, all of Kermit's file collision actions are
  1544.        available: backup, update, refuse, rename, etc.
  1545.      * Multi-file transfers can be interrupted on a per-file basis,
  1546.        automatically skipping to the next file.
  1547.      * FTP sessions are [191]fully scriptable.
  1548.      * An entire FTP session (connect, login, CD, upload or download,
  1549.        logout) can be specified on the command line without using a
  1550.        script.
  1551.      * All of Kermit's logging options and formats are available to keep
  1552.        an accurate and complete record of each connection and file
  1553.        transfer, and to aid in troubleshooting.
  1554.      * All of Kermit's file-transfer display options are available
  1555.        (fullscreen, brief, CRT, serial, none).
  1556.        
  1557.    And best of all:
  1558.      * Kermit doesn't give you those annoying per-file prompts every time
  1559.        you start a multi-file transfer without remembering to give a
  1560.        "prompt" command first :-).
  1561.        
  1562.    [ [192]Top ] [ [193]Contents ] [ [194]FTP Client Overview ] [ [195]FTP
  1563.    Script Tutorial ] [ [196]C-Kermit Home ] [ [197]Kermit Home ]
  1564.      _________________________________________________________________
  1565.    
  1566.   3.1. Making and Managing FTP Connections
  1567.   
  1568.    Each copy of Kermit can have one FTP connection open at a time. FTP
  1569.    connections are independent of regular terminal connections; a
  1570.    terminal connection (serial or network via SET LINE, DIAL, SET HOST,
  1571.    TELNET, etc) may be, but need not be, open at the same time as an FTP
  1572.    connection, and terminal connections can also be closed, and new
  1573.    connections opened, without interfering with the FTP connection (and
  1574.    vice versa). Thus, for example, Kermit can have an FTP connection and
  1575.    a TELNET connection open to the same host simultaneously, using the
  1576.    TELNET connection (e.g.) to send mail or take other desired actions as
  1577.    various FTP actions complete. Of course, each copy of Kermit can do
  1578.    only one thing at a time, so it can't (for example) transfer a file
  1579.    with FTP and another file with Kermit protocol simultaneously.
  1580.    
  1581.    A Kermit FTP session can be established by [198]command-line options,
  1582.    by [199]URL, or by [200]interactive commands.
  1583.    
  1584.     3.1.1. Kermit Command-Line Options for FTP
  1585.     
  1586.    The new command-line option '-9' (sorry, we're out of letters) can be
  1587.    used when starting C-Kermit, telling it to make an FTP connection:
  1588.    
  1589.   kermit -9 hostname
  1590.  
  1591.    or if a non-default FTP port is needed:
  1592.    
  1593.   kermit -9 hostname:port
  1594.  
  1595.    You can also specify the username on the command line with the -M ("My
  1596.    User ID") option that was already there for other connection types:
  1597.    
  1598.   kermit -9 hostname -M olga
  1599.  
  1600.    If you specify the username on the command line, Kermit uses it when
  1601.    making the connection and does not prompt you for it (but it does
  1602.    prompt you for the password if one is required).
  1603.    
  1604.    Once the connection is made, you get the regular Kermit prompt, and
  1605.    can give interactive commands such as the ones described below. When
  1606.    you give a BYE command, Kermit closes the session and exits, just as a
  1607.    regular FTP client would do. If you don't want Kermit to exit when you
  1608.    give a BYE command, include the -S ("Stay") option on the command
  1609.    line.
  1610.    
  1611.    Other Kermit command-line options that are not specific to non-FTP
  1612.    connections should affect the FTP session in the expected ways; for
  1613.    example, -i and -T force binary and text mode transfers, respectively.
  1614.    
  1615.    File transfers can not be initiated on the "kermit -9" command line;
  1616.    for that you need to use Kermit's FTP personality (next section) or
  1617.    you can use URLs ([201]Section 3.1.3).
  1618.      _________________________________________________________________
  1619.    
  1620.     3.1.2. The FTP Command-Line Personality
  1621.     
  1622.    If you want to replace your regular FTP client with C-Kermit, you can
  1623.    make a link called "ftp" to the C-Kermit binary (or you can store a
  1624.    copy of the C-Kermit binary under the name "ftp"). When C-Kermit is
  1625.    invoked with a program name of "ftp" (or "FTP", case doesn't matter),
  1626.    it assumes the command-line personality of the regular FTP client:
  1627.    
  1628.   ftp [ options ] hostname [ port ]
  1629.  
  1630.    In this case the options are like those of a regular FTP client:
  1631.    
  1632.   -d  Debug: enables debug messages and creates a debug.log file.
  1633.   -n  No autologin: Kermit should not send your user ID automatically.
  1634.   -t  Packet trace: accepted but is treated the same as -d.
  1635.   -v  Verbose: accepted but ignored (operation is verbose by default).
  1636.   -i  Not interactive: accepted but ignored.
  1637.  
  1638.    and the hostname can also be a URL (explained in [202]Section 3.1.3).
  1639.    To specify a non-default TCP port for the FTP server, include the port
  1640.    number or name after the hostname.
  1641.    
  1642.    There are also some bonus options that allow you to execute an entire
  1643.    FTP session from the shell command line, as long as you don't include
  1644.    the -n option. These are not available with regular FTP clients, and
  1645.    at least one of these options (-g) conflicts with UNIX ftp (where -g
  1646.    means "no globbing", which does not apply to Kermit), and some of them
  1647.    (like the options above) also conflict with regular Kermit
  1648.    command-line options:
  1649.    
  1650.   -m mode      = "passive" (default) or "active"
  1651.   -Y            Don't execute the Kermit initialization file [1]
  1652.   -q            Quiet, suppresses all but error messages [1]
  1653.   -S            Stay, don't exit automatically [1]
  1654.   -A            Autologin anonymously [2]
  1655.   -u name       Username for autologin [2] (synonym: -M [1])
  1656.   -P password   Password for autologin (see cautions below) [2]
  1657.   -D directory  cd after autologin [2]
  1658.   -b            Binary mode [2]
  1659.   -a            Text ("ascii") mode [2] (synonym: -T [1])
  1660.   -R            Recursive (works with -p) [4]
  1661.   -p files      Files to put (upload) after autologin [2] (synonym: -s [1])
  1662.   -g files      Files to get (download) after autologin [3]
  1663.  
  1664.    [1] Same as Kermit, not available in regular FTP clients.
  1665.    [2] Conflicts with Kermit, not available in regular FTP clients.
  1666.    [3] Same as Kermit, conflicts with regular FTP clients.
  1667.    [4] Conflicts with Kermit, available in some FTP clients.
  1668.    
  1669.    Fancier options such as restart, character-set translation, filename
  1670.    collision selection, automatic move/rename/delete, etc, are not
  1671.    available from the command line; for these you can use the commands
  1672.    described in the following sections. The -R might also work with -g
  1673.    (GET) but that depends on the server.
  1674.    
  1675.    The following security options are also available, explained in
  1676.    [203]Section 3.2:
  1677.    
  1678.   -k realm      Kerberos 4 realm [4]
  1679.   -f            Kerberos 5 credentials forwarding [4]
  1680.   -x            autoencryption mode [4]
  1681.   -c cipher     SRP cipher type [4]
  1682.   -H hash       SRP encryption hash [4]
  1683.   -z option     Security options [4]
  1684.  
  1685.    If you include -A or specify a name of "anonymous" or "ftp", you are
  1686.    logged in anonymously and, in the absence of -P, Kermit automatically
  1687.    supplies a password of "user@host", where "user" is your local user
  1688.    ID, and "host" is the hostname of the computer where Kermit is
  1689.    running. If you do not include -p or -g, Kermit enters command mode so
  1690.    you can type commands or execute them from a script.
  1691.    
  1692.    If you include -p or -g, Kermit attempts to transfer the specified
  1693.    files and then exits automatically at the end of the transfer unless
  1694.    you also included -S (Stay). It uses the "brief" file transfer display
  1695.    (one line per file) unless you include the -q option to suppress it.
  1696.    
  1697.    When uploading files with -p, Kermit switches automatically between
  1698.    text and binary mode for each file.
  1699.    
  1700.    When downloading, you can either specify a particular mode (text or
  1701.    binary) to be used for all the files, or you can let Kermit select the
  1702.    type for each file automatically, based on its name (see [204]Sections
  1703.    3.5 and [205]3.6 for greater detail). In UNIX be sure to quote any
  1704.    wildcard characters to prevent the shell from expanding them, as shown
  1705.    in the examples just below. Filename collisions are handled according
  1706.    Kermit's FILE COLLISION setting (if specified in your Kermit
  1707.    customization file; otherwise the default, which is BACKUP).
  1708.    
  1709.    It should go without saying that the -P option should be used with
  1710.    caution. In addition to the well-known risks of transmitting plaintext
  1711.    passwords over the Internet, in this case the password also echos to
  1712.    the screen if you type it, and can be seen in ps and w listings that
  1713.    show the user's currently active command and command-line arguments.
  1714.    Thus command-line FTP sessions are most appropriate for secure or
  1715.    anonymous connections (those that do not require passwords).
  1716.    
  1717.    Here's an example in which you download the latest C-Kermit "tarball"
  1718.    from the Columbia University FTP archive:
  1719.    
  1720.   ftp -A kermit.columbia.edu -bg kermit/archives/ckermit.tar.gz
  1721.  
  1722.    This assumes that "ftp" is a symbolic link to C-Kermit. It logs you in
  1723.    anonymously and gets the ckermit.tar.gz file in binary mode from the
  1724.    kermit/archives directory.
  1725.    
  1726.    Here's a slightly more ambitious example that illustrates CD'ing to
  1727.    the desired server directory to get a group of files in text mode (in
  1728.    this case the C-Kermit source files):
  1729.    
  1730.   ftp -A kermit.columbia.edu -D kermit/f -ag "ck[cuw]*.[cwh]" makefile
  1731.  
  1732.    In this case we CD to the kermit/f directory so we don't have to
  1733.    include it in each file specification, and we quote the ck[cuw]*.[cwh]
  1734.    specification so the shell doesn't expand it, since we have to pass it
  1735.    as-is to the server. Note also that the quotes don't go around the
  1736.    entire file list; only around each file specification that needs to be
  1737.    quoted.
  1738.    
  1739.    Here's one more example, that uploads a debug log file in binary mode
  1740.    to the Kermit incoming directory (as we might ask you to do when
  1741.    following up on a problem report):
  1742.    
  1743.   ftp -A kermit.columbia.edu -D kermit/incoming -bp debug.log
  1744.  
  1745.    In this case the -D option is required to tell the server where to put
  1746.    the incoming file.
  1747.    
  1748.    Unless the -Y option is included, your Kermit initialization file
  1749.    (.kermrc in UNIX, K95.INI in Windows) is executed before the command
  1750.    line options, so you can set any FTP-related preferences there, as
  1751.    described in the subsequent sections.
  1752.      _________________________________________________________________
  1753.    
  1754.     3.1.3. The FTP URL Interpreter
  1755.     
  1756.    If Kermit is invoked with either its regular personality (as "kermit")
  1757.           or its FTP personality (as "ftp"), you can also give a URL
  1758.           (Universal Resource Locator) instead of a hostname and options,
  1759.           with or without a username and password:
  1760.           ftp ftp://user:password@host/path
  1761.           ftp ftp://user@host/path
  1762.           ftp ftp://host/path
  1763.           kermit ftp://host/path
  1764.           
  1765.    If the FTP personality is used, the service must be "ftp". In all
  1766.    cases, a hostname or address must be included. If a user is included
  1767.    but no password, you are prompted for the password. If a path
  1768.    (filename) is included:
  1769.      * If no user is included, "anonymous" is used.
  1770.      * GET is assumed.
  1771.        
  1772.    If no path (and no action options) are included, an interactive FTP
  1773.           session is started, as in this example:
  1774.           ftp ftp://kermit.columbia.edu
  1775.           
  1776.    If a path is included, but a username is not included, "anonymous" is
  1777.    used and an appropriate user@host password is supplied automatically.
  1778.    If authentication is successful, Kermit attempts to GET the file
  1779.    indicated by the path or, if the path is the name of a directory, it
  1780.    asks the server for a directory listing. In both cases, Kermit
  1781.    disconnects from the server and exits after the operation is complete
  1782.    (unless you have included the -S option on the command line).
  1783.    
  1784.    Here's an example that gets a listing of the Kermit directory at the
  1785.           Kermit ftp site:
  1786.           ftp ftp://kermit.columbia.edu/kermit/
  1787.           
  1788.    This example gets the top-level READ.ME file from the same directory:
  1789.           ftp ftp://kermit.columbia.edu/kermit/READ.ME
  1790.           
  1791.    Here's the same example, but requesting a text-mode transfer:
  1792.           ftp -T ftp://kermit.columbia.edu/kermit/READ.ME
  1793.           This illustrates that you can mix command-line options and URLs
  1794.           if you desire.
  1795.           
  1796.    Here's an example that logs in as a (fictitious) real user to get a
  1797.           file:
  1798.           ftp ftp://olga@ftp.xyzcorp.com/resume.txt
  1799.           The password is not included, so Kermit prompts for it.
  1800.           
  1801.    This scheme allows Kermit to be used as the FTP helper of other
  1802.    applications, such as Web browsers, with all its advantages over other
  1803.    FTP clients (especially the ones that are built in to most Web
  1804.    browsers), e.g. that it can be given wildcards, and it can pick text
  1805.    and binary mode automatically for each file.
  1806.    
  1807.    HINT: suppose somebody sends you an FTP URL in email, or you see it in
  1808.    some text. If your terminal screen supports copy/paste, copy the url,
  1809.    and then at the shell prompt type "kermit", a space, and then paste
  1810.    the URL, e.g.:
  1811.    
  1812.   $ kermit ftp://alpha.greenie.net/pub/mgetty/source/1.1/mgetty1.1.27-O
  1813.  
  1814.    "$ is the shell prompt; the part you type is underlined, the rest is
  1815.    pasted in. Kermit does the rest.
  1816.      _________________________________________________________________
  1817.    
  1818.     3.1.4. Interactive FTP Session Establishment
  1819.     
  1820.    As you read this and the following sections, bear in mind that any
  1821.    command that can be given at the prompt can also be used in a script
  1822.    program. Kermit's script programming language is the same as its
  1823.    interactive command language. [206]CLICK HERE if you would like to
  1824.    learn a bit more about script writing.
  1825.    
  1826.    An FTP session is established with the FTP OPEN command:
  1827.    
  1828.    FTP [ OPEN ] [ { /SSL, /TLS } ] hostname [ switches ] [ port ]
  1829.           Opens an FTP connection to the given host on the given port
  1830.           and, if FTP AUTOLOGIN is ON, also logs you in to the server,
  1831.           prompting for username and password if necessary. If no port is
  1832.           specified, the regular FTP protocol port (21) is used. The OPEN
  1833.           keyword is optional (unless the hostname conflicts with one of
  1834.           the FTP command keywords, which you can list by typing "ftp
  1835.           ?").
  1836.           
  1837.    The hostname can be an IP host name, numeric IP address, or if you
  1838.    have a network directory active (SET NETWORK DIRECTORY; see Chapter 6
  1839.    of [207]Using C-Kermit), an entry name in the directory. In the latter
  1840.    case, if the given hostname matches exactly one entry, the associated
  1841.    name or address is used; if it matches more than one, Kermit cycles
  1842.    through them until one is found that can be opened; if it matches
  1843.    none, then the hostname is used as-is. If a directory is active but
  1844.    you want to bypass directory lookup, include an "=" sign at the
  1845.    beginning of the hostname, and/or use a numeric IP address.
  1846.    
  1847.    When an FTP connection is opened, the default file-transfer mode is
  1848.    set to binary if the client and server platforms are alike (e.g. both
  1849.    of them are some kind of UNIX), and to text ("ascii") if they are not
  1850.    alike. This has no particular effect for uploading since Kermit
  1851.    automatically switches between text and binary mode for each file, but
  1852.    might be important for downloading. The connection is also set to
  1853.    Stream mode and File structure. Record- or page-oriented file
  1854.    transfers are not supported by C-Kermit's FTP client.
  1855.    
  1856.    The optional FTP OPEN switches are:
  1857.    
  1858.    /ANONYMOUS
  1859.           Logs you in anonymously, automatically supplying username
  1860.           "anonymous" and user@host as the password, based on your local
  1861.           user and host names.
  1862.           
  1863.    /USER:name
  1864.           Uses the given username to log you in, thus avoiding the Name:
  1865.           prompt.
  1866.           
  1867.    /PASSWORD:text
  1868.           Uses the given text as your password, thus avoiding the
  1869.           Password: prompt. This switch is not recommended for use in
  1870.           script files, which would be a security risk.
  1871.           
  1872.    /ACCOUNT:text
  1873.           Uses the given text as your account (or secondary password,
  1874.           depending on the requirements of the server; most servers do
  1875.           not require or accept an account name). If an account is not
  1876.           supplied, you are not prompted for one.
  1877.           
  1878.    /PASSIVE
  1879.           Opens the connection in passive mode. Passive mode is the
  1880.           default in Kermit's FTP client, unlike in most others, since it
  1881.           works better through firewalls. The /PASSIVE and /ACTIVE
  1882.           switches apply only to the connection that is being opened, and
  1883.           do not affect the global FTP PASSIVE-MODE setting.
  1884.           
  1885.    /ACTIVE
  1886.           Opens the connection in active mode. Use this switch if the
  1887.           server does not support passive mode, or use the command SET
  1888.           FTP PASSIVE-MODE OFF.
  1889.           
  1890.    /NOINIT
  1891.           Added in C-Kermit 8.0.201.   Tells C-Kermit not to send REST,
  1892.           STRU, and MODE commands to the server when the connection is
  1893.           opened, since these have been reported to cause confusion in
  1894.           certain servers.
  1895.           
  1896.    When a username or password is missing, a prompt is issued at the
  1897.    controlling terminal and you must type the response; the response can
  1898.    not be scripted. Use the switches to avoid prompts, or one of the
  1899.    secure authentication methods described in the next section, or see
  1900.    [208]SET FTP AUTOLOGIN and the [209]FTP USER and similar commands
  1901.    described later in this section.
  1902.    
  1903.    Examples:
  1904.    
  1905.   ftp open kermit.columbia.edu /anonymous  ; Open and log in anonymously
  1906.   ftp kermit.columbia.edu /anonymous       ; The OPEN keyword can be omitted
  1907.   ftp xyzcorp.com                          ; Open and maybe prompt for username
  1908.   ftp xyzcorp.com /user:olga               ; Open and log in as olga
  1909.   ftp testing.abccorp.com 449              ; Specify a special TCP port number
  1910.   ftp testing.abccorp.com /user:olaf /password:secret 449
  1911.  
  1912.    The FTP OPEN command succeeds if a connection was opened to the server
  1913.    (even if the given username and password were not valid) and fails
  1914.    otherwise (see [210]Section 3.8 for details).
  1915.    
  1916.    When your FTP session is complete, you can terminate it as follows:
  1917.    
  1918.    FTP BYE
  1919.           Closes the FTP connection if one was open. The FTP prefix can
  1920.           be omitted if no other connection is open at the same time (see
  1921.           [211]Section 3.8 for details). If a connection log is active,
  1922.           an FTP record is written to it. If Kermit was started with the
  1923.           -9 command-line option or with its FTP command-line
  1924.           personality, and the -S (Stay) option was not given, AND there
  1925.           is no other active connection, the FTP BYE command also exits,
  1926.           just as it does on a regular FTP client. Synonyms: FTP CLOSE,
  1927.           FTP QUIT (but if the FTP prefix is omitted from QUIT, this
  1928.           becomes the regular Kermit QUIT command, which is equivalent to
  1929.           EXIT; i.e. it closes the connection and exits from Kermit).
  1930.           
  1931.    The following commands can be used to achieve greater control over the
  1932.    connection and login process:
  1933.    
  1934.    SET FTP AUTOLOGIN { ON, OFF }
  1935.           If you give this command prior to opening an FTP connection, it
  1936.           controls whether Kermit tries to log you in automatically as
  1937.           part of the connection process. Normally ON, which means the
  1938.           username and password are sent automatically (and prompted for
  1939.           if they are not yet known). When OFF, FTP OPEN connects to the
  1940.           server without logging in. OFF is equivalent to the -n
  1941.           command-line option when using Kermit's FTP command-line
  1942.           personality.
  1943.           
  1944.    FTP USER name [ password [ account ] ]
  1945.           Used to log in to an FTP server to which a connection has been
  1946.           made without autologin, or when autologin failed. If the
  1947.           password is furnished on the command line, it is used;
  1948.           otherwise you are prompted for a password. An account may also
  1949.           be furnished if required by the server; it is not required by
  1950.           Kermit and is not prompted for if omitted. Synonyms: USER, FTP
  1951.           LOGIN.
  1952.           
  1953.    FTP ACCOUNT text
  1954.           Sends an account name to a server that supports accounts. If
  1955.           the server does not support accounts, an error response occurs.
  1956.           If the server does support accounts, the account is accepted if
  1957.           it is valid and rejected if it is not. The account might be
  1958.           used for charging purposes or it might be a secondary password,
  1959.           or it might be used for any other purpose, such as an access
  1960.           password for a particular disk. Servers that support accounts
  1961.           might or might not allow or require the account to be sent
  1962.           prior to login; usually it is sent after login, if at all.
  1963.           Synonym: ACCOUNT.
  1964.           
  1965.    Example:
  1966.    
  1967.   set ftp autologin off                  ; One thing at a time please
  1968.   ftp xyzcorp.com                        ; Try to make the connection
  1969.   if fail exit 1 FTP connection failed   ; Check that it was made
  1970.   ftp user olga secret                   ; Now log in to the server
  1971.   if fail exit 1 FTP login failed        ; Check that it worked
  1972.   ftp account 103896854                  ; Login OK - send account
  1973.   if fail echo WARNING - FTP ACCT failed ; Warn if problem
  1974.   ...                                    ; (have session here)
  1975.   bye                                    ; Log out and disconnect
  1976.  
  1977.    The following commands are used to control or get information about
  1978.    the FTP connection. Any particular FTP server does not necessarily
  1979.    support all of them.
  1980.    
  1981.    FTP RESET
  1982.           Terminates a user session but leaves the connection open,
  1983.           allowing a new login via FTP USER.
  1984.           
  1985.    FTP IDLE [ number ]
  1986.           Most FTP servers automatically log you out and and disconnect
  1987.           your session if there has been no activity for a certain amount
  1988.           of time. Use this command to ask the server to set its idle
  1989.           limit to the given number of seconds. Omit the number to ask
  1990.           the server to inform you of its current idle limit.
  1991.           
  1992.    FTP STATUS [ filename ]
  1993.           Asks the FTP server to send information about the current
  1994.           session. The result is a free-format report that might include
  1995.           server identification, username and login time, FTP protocol
  1996.           settings, and file-transfer statistics. If a filename is given,
  1997.           the server is supposed to send detailed information about the
  1998.           file.
  1999.           
  2000.    FTP SYSTEM
  2001.           Asks the FTP server to identify its operating system (Listed in
  2002.           Internet Assigned Numbers, Operating System Names). Examples:
  2003.           UNIX, VMS, VM/CMS, WINDOWS-NT. Unfortunately many variations
  2004.           are allowed (e.g. LINUX-2.0, LINUX-2.2, FREEBSD, ULTRIX, etc,
  2005.           instead of UNIX; WINDOWS-NT-3, WINDOWS-NT-3.5, WINDOWS-NT-3.51,
  2006.           WINDOWS-NT-4, etc). The report might also include other
  2007.           information like "Type L8", "Type I", or "Type A", indicating
  2008.           the file-transfer mode.
  2009.           
  2010.    FTP HELP [ keyword [ keyword [ ... ] ]
  2011.           Asks the server to list the commands it supports. The response
  2012.           is usually cryptic, listing FTP command mnemonics, not the
  2013.           commands used by the client (since the server has no way of
  2014.           knowing anything about the client's user interface). For
  2015.           example, the PUT command is STOR in FTP protocol. If a keyword
  2016.           is given, which should be an FTP protocol command,
  2017.           slightly-more- detailed help is given about the corresponding
  2018.           command (if the FTP server supports this feature). Examples:
  2019.           "ftp help", "ftp help stor".
  2020.           
  2021.    FTP SITE text
  2022.           (Advanced) Sends an FTP SITE (site-specific) command. Usually
  2023.           this means that the FTP server is asked to run an external
  2024.           command with the given arguments. You might be able to find out
  2025.           what SITE commands are available by sending "ftp help site" to
  2026.           the server, but in general the availability of and response to
  2027.           SITE commands is (not surprisingly) site specific.
  2028.           
  2029.    FTP QUOTE text
  2030.           (Advanced) Sends an FTP command in FTP protocol format. Use
  2031.           this command to send commands to the server that the FTP client
  2032.           might not know about.
  2033.           
  2034.    SHOW FTP
  2035.           Lists client (Kermit) FTP settings and information. Also SHOW
  2036.           CONNECTION, SHOW COMMUNICATIONS.
  2037.           
  2038.    HELP FTP [ keyword ]
  2039.           Asks Kermit to list and describe its built-in FTP commands.
  2040.           
  2041.    HELP SET FTP [ keyword ]
  2042.           Asks Kermit to list and describe its built-in SET FTP commands.
  2043.           
  2044.    [ [212]Top ] [ [213]Contents ] [ [214]C-Kermit Home ] [ [215]Kermit
  2045.    Home ]
  2046.      _________________________________________________________________
  2047.    
  2048.   3.2. Making Secure FTP Connections
  2049.   
  2050.    In the previous section, you can see several examples of traditional
  2051.    insecure authentication: username and password sent across the network
  2052.    in clear text. Of course this is bad practice on at least two counts:
  2053.    (1) storing passwords in files (such as script files) gives access to
  2054.    the target systems to anybody who can obtain read access to your
  2055.    scripts; and (2) sending this information over the network leaves it
  2056.    open to interception by network sniffers or compromised hosts.
  2057.    
  2058.    Because of the increasing need for security on the Internet, FTP
  2059.    servers are beginning to appear that offer secure forms of
  2060.    authentication, in which no information is sent over the network that
  2061.    would allow anyone who intercepts it to usurp your identity and gain
  2062.    your access rights.
  2063.    
  2064.    Kermit provides an equivalent form of FTP security for each type of
  2065.    IETF standard security implemented in Telnet. These include
  2066.    GSSAPI-KERBEROS5, KERBEROS4, Secure Remote Password (SRP), and
  2067.    Transport Layer Security (SSL and TLS). It does not presently include
  2068.    SSL tunneling nor any form of SSH v1 or v2. When Kermit is built with
  2069.    the necessary libraries, secure FTP connections are attempted by
  2070.    default, in which all connections are authenticated and the command
  2071.    and data channels are private.
  2072.    
  2073.    The use of authentication and encryption for FTP connections can be
  2074.    adjusted with the commands listed below, which are available only if
  2075.    your version of Kermit was built with the corresponding security
  2076.    options and libraries:
  2077.    
  2078.    SET FTP AUTHTYPE { AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS }
  2079.           Specifies an ordered list of authentication methods to be
  2080.           attempted when AUTOAUTHENTICATION is ON. The default list is:
  2081.           GSSAPI-KRB5, SRP, KERBEROS_V4, TLS, SSL. If none of the
  2082.           selected methods are supported by the server, an insecure login
  2083.           is used as a fallback. Note, by the way, that SSL or TLS can be
  2084.           used to secure an anonymous connection.
  2085.           
  2086.    SET FTP AUTOAUTHENTICATION { ON, OFF }
  2087.           Tells whether authentication should be negotiated by the FTP
  2088.           OPEN command. Default is ON.
  2089.           
  2090.    SET FTP AUTOENCRYPTION { ON, OFF }
  2091.           Tells whether encryption (privacy) should be negotiated by the
  2092.           FTP OPEN command. Default is ON.
  2093.           
  2094.    SET FTP AUTOLOGIN { ON, OFF }
  2095.           Tells Kermit whether to try logging in automatically when you
  2096.           make an FTP connection, as opposed to letting you do it "by
  2097.           hand" with the FTP USER command.
  2098.           
  2099.    SET FTP COMMAND-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE
  2100.           }
  2101.           Determines the level of protection applied to the command
  2102.           channel:
  2103.           
  2104.   CLEAR         Data is sent in plaintext and not protected against tampering.
  2105.   CONFIDENTIAL  Data is encrypted but not protected against tampering.
  2106.   PRIVATE       Data is encrypted and is protected against tampering.
  2107.   SAFE          Data is sent in plaintext but protected against tampering.
  2108.  
  2109.           The default is PRIVATE.
  2110.           
  2111.    SET FTP CREDENTIAL-FORWARDING { ON, OFF }
  2112.           Tells whether end-user credentials are to be forwarded to the
  2113.           server if supported by the authentication method (GSSAPI-KRB5
  2114.           only). This is often required to allow access to distributed
  2115.           file systems (e.g. AFS.)
  2116.           
  2117.    SET FTP DATA-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE }
  2118.           Tells what level of protection is applied to subsequent data
  2119.           channels. The meanings of the protection-level keywords are the
  2120.           same as for SET FTP COMMAND-PROTECTION-LEVEL. The default is
  2121.           PRIVATE.
  2122.           
  2123.    SET FTP SRP CIPHER name
  2124.           Specifies the cipher to be used for encryption when SRP
  2125.           authentication is in use. The list of possible choices is
  2126.           computed based on the capabilities of the local SRP library and
  2127.           includes NONE plus zero or more of the following:
  2128.           
  2129.   BLOWFISH_ECB        CAST5_ECB          DES_ECB          DES3_ECB
  2130.   BLOWFISH_CBC        CAST5_CBC          DES_CBC          DES3_CBC
  2131.   BLOWFISH_CFB64      CAST5_CFB64        DES_CFB64        DES3_CFB64
  2132.   BLOWFISH_OFB64      CAST5_OFB64        DES_OFB64        DES3_OFB64
  2133.  
  2134.           The default is DES3_ECB.
  2135.           
  2136.    SET FTP SRP HASH name
  2137.           Specifies the hash to be used for data protection when SRP
  2138.           authentication is in use. The choices are MD5 and SHA. The
  2139.           default is SHA.
  2140.           
  2141.    Command-line options:
  2142.    
  2143.    -k name
  2144.           Specifies the realm to be used with Kerberos 4 authentication
  2145.           (= SET AUTH K4 REALM name).
  2146.           
  2147.    -f
  2148.           Enables forwarding of Kerberos 5 credentials to the host when
  2149.           using GSSAPI authentication (= SET AUTH K5 FORWARDABLE ON).
  2150.           
  2151.    -x
  2152.           Enables autoencryption (= SET FTP AUTOENCRYPTION ON).
  2153.           
  2154.    -c cipher
  2155.           Specifies the kind of cipher to be used for encryption with SRP
  2156.           authentication. Equivalent to SET FTP SRP CIPHER, with the same
  2157.           choices. If this option is not given, CAST5_CBC is used.
  2158.           
  2159.    -H hash
  2160.           Specifies the hash to be used for encryption with SRP
  2161.           authentication. Equivalent to SET FTP SRP HASH, with the same
  2162.           choices. If this option is not given, SHA is used.
  2163.           
  2164.    -z debug
  2165.           Turns on SSL/TLS debugging.
  2166.           
  2167.    -z secure
  2168.           Requires secure connection.
  2169.           
  2170.    -z certsok
  2171.           Says to accept all certificates without checking validity.
  2172.           
  2173.    -z verify=n
  2174.           Sets certificate verification mode to the given number, n:
  2175.             0 = no verification
  2176.             1 = verify certificate if presented
  2177.             2 = require verification of certificate
  2178.           
  2179.    -z cert=filename
  2180.           Specifies a file containing a client certificate to be
  2181.           presented to the FTP server.
  2182.           
  2183.    -z key=filename
  2184.           Specifies a file containing a private key matching the client
  2185.           certificate.
  2186.           
  2187.    -z !krb4
  2188.           nokrb4 Disables the use of Kerberos 4.
  2189.           
  2190.    -z !gss
  2191.           
  2192.    -z nogss
  2193.           Disables the use of GSSAPI - Kerberos 5.
  2194.           
  2195.    -z !srp
  2196.           
  2197.    -z nosrp
  2198.           Disables use of SRP.
  2199.           
  2200.    -z !ssl
  2201.           
  2202.    -z nossl
  2203.           Disables the use of SSL.
  2204.           
  2205.    -z !tls
  2206.           
  2207.    -z notls
  2208.           Disables the use of TLS.
  2209.           
  2210.    Caution: If your FTP connection is secured via AUTH TLS, it is not
  2211.    possible to interrupt a file transfer. This is a limitation of all
  2212.    known FTP servers that support AUTH TLS.
  2213.    
  2214.    [ [216]Top ] [ [217]Contents ] [ [218]C-Kermit Home ] [ [219]Kermit
  2215.    Home ]
  2216.      _________________________________________________________________
  2217.    
  2218.   3.3. Setting FTP Preferences
  2219.   
  2220.    FTP preferences can be set globally and persistently with the commands
  2221.    in the following sections; many of these can also be overridden on a
  2222.    per-command basis with switches that have the same name.
  2223.    
  2224.     3.3.1. Logs, Messages, and Other Feedback
  2225.     
  2226.    You can control the amount of feedback received from your FTP session
  2227.    with the commands in this section. First, you can create a log of your
  2228.    FTP transfers with the following commands:
  2229.    
  2230.    SET TRANSACTION-LOG { VERBOSE, FTP, BRIEF }
  2231.           Selects the log format. VERBOSE is the default, and is
  2232.           described in [220]the manual. FTP chooses a WU-FTPD format, the
  2233.           same as is used by the popular FTP server. BRIEF creates
  2234.           per-file records in comma-separated-list format. For greater
  2235.           detail, see [221]Section 4.17 of the [222]C-Kermit 7.0 Update
  2236.           Notes.
  2237.           
  2238.    LOG TRANSACTIONS filename
  2239.           Records FTP (or Kermit, or any other protocol) uploads and
  2240.           downloads in the given file using the format selected by the
  2241.           most recent SET TRANSACTION-LOG command, if any, or else the
  2242.           default format.
  2243.           
  2244.    FTP screen messages and displays are controlled by the following
  2245.    commands:
  2246.    
  2247.    SET TRANSFER DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE, OFF }
  2248.           FTP transfers use Kermit's normal file-transfer display styles.
  2249.           Use this command to choose the desired format; the default on
  2250.           most platforms is FULLSCREEN. The display is automatically
  2251.           disabled if Kermit is running in the background or in batch.
  2252.           BRIEF is always used for command-line initiated transfers
  2253.           (unless suppressed by -q). While a file-transfer is in
  2254.           progress, you can interrupt it in the normal Kermit way by
  2255.           typing one of the following keys or key combinations:
  2256.             X - Cancel current file but go on to the next one (if any).
  2257.             Z - Cancel the entire transfer.   Ctrl-L or Ctrl-W - Refresh
  2258.           the file-transfer display (if any).
  2259.           
  2260.    SET QUIET { ON, OFF }
  2261.           This command applies to Kermit in general, not just FTP. OFF by
  2262.           default; when ON, it surpresses most messages from most
  2263.           commands as well as the file-transfer display.
  2264.           
  2265.    SET FTP PROGRESS-MESSAGES { ON, OFF }
  2266.           Tells whether Kermit should print locally-generated feedback
  2267.           messages for each non-file-transfer command. ON by default.
  2268.           
  2269.    SET FTP VERBOSE-MODE { ON, OFF }
  2270.           Tells whether to display all responses from the FTP server. OFF
  2271.           by default. This shows all responses to all commands, except
  2272.           when the file-transfer display is active, and unless you have
  2273.           SET QUIET ON. When OFF, responses are shown only for commands
  2274.           such as FTP PWD whose purpose is to display a response.
  2275.           
  2276.    SET FTP DEBUG { ON, OFF }
  2277.           Tells whether local client debugging information should be
  2278.           displayed. OFF by default. When ON, the commands that are sent
  2279.           to the server are shown, as well as its responses (even if
  2280.           VERBOSE-MODE is OFF), plus additional informational messages
  2281.           are printed regarding the progress of secure operations. Also,
  2282.           the temporary file created by the [223]MGET command is not
  2283.           deleted so you can see what's in it.
  2284.           
  2285.    Set all of these to OFF when silent running is desired.
  2286.    
  2287.     3.3.2. Operational Preferences
  2288.     
  2289.    SET FTP AUTOLOGIN { ON, OFF }
  2290.           If you give this command prior to opening an FTP connection, it
  2291.           controls whether Kermit tries to log you in automatically as
  2292.           part of the connection process. Normally ON, which means the
  2293.           username and password are sent automatically (and prompted for
  2294.           if they are not yet known). When OFF, FTP OPEN connects to the
  2295.           server without logging in. OFF is equivalent to the -n
  2296.           command-line option when using Kermit's FTP command-line
  2297.           personality. See [224]Section 3.1.4 for usage.
  2298.           
  2299.    SET FTP PASSIVE-MODE { ON, OFF }
  2300.           ON by default, to avoid random TCP port assignment for data
  2301.           connections, which can prevent FTP protocol from working
  2302.           through firewalls and network address translators (for more on
  2303.           these topics, see the [225]Kermit security reference. Set to
  2304.           OFF in case the FTP server does not support passive mode, or in
  2305.           case the client has problems with it (it has been observed, for
  2306.           example, that when using passive mode, the SCO XENIX 2.3.4
  2307.           TCP/IP stack hangs in the connect() call forever).
  2308.           
  2309.    SET FTP SEND-PORT-COMMANDS { ON, OFF }
  2310.           This command determines whether the FTP client sends a new PORT
  2311.           command to the server when accepting incoming data connections
  2312.           (as when not using passive mode.) When PASSIVE-MODE is OFF and
  2313.           SET SEND-PORT is OFF, the port that was originally specified is
  2314.           reused. This is the default behavior for normal FTP clients but
  2315.           it is not compatible with many firewalls.
  2316.           
  2317.    SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
  2318.           Whether to translate character sets when transferring files
  2319.           with FTP (explained in [226]Section 3.7). OFF by default.
  2320.           
  2321.    SET FTP SERVER-CHARACTER-SET name
  2322.           Tells Kermit the character set used by the FTP server, UTF-8 by
  2323.           default ([227]Section 3.7).
  2324.           
  2325.    SET FTP ERROR-ACTION { PROCEED, QUIT }
  2326.           When transferring a group of files with FTP, and an error
  2327.           occurs with one of the files, Kermit normally goes on the next
  2328.           file. Use SET FTP ERROR-ACTION to QUIT to make Kermit stop the
  2329.           transfer immediately and fail if an error occurs with any
  2330.           single file in the group. Example: you have given Kermit a list
  2331.           of files to send, and one of the files can not be found, or
  2332.           read permission is denied. Note that cancelling a file by
  2333.           typing 'X' during transfer is not considered an error (if you
  2334.           want to cancel the entire transfer, type 'Z' or Ctrl-C).
  2335.           
  2336.    SET FTP PERMISSIONS { AUTO, ON, OFF }
  2337.           When uploading files with PUT or MPUT, this tells whether
  2338.           Kermit should send each file's permissions. The default is OFF,
  2339.           which means not to send permissions, in which case the uploaded
  2340.           file's permissions are set by the FTP server according to its
  2341.           own criteria. ON means to send them, AUTO means to send them
  2342.           only if the client (Kermit) and server are on like platforms
  2343.           (e.g. both UNIX). This command has no effect when downloading,
  2344.           since the FTP protocol does not include a way for the server to
  2345.           inform the client of a file's permissions. Also see [228]FTP
  2346.           PUT /PERMISSIONS. Note that setting permissions after uploading
  2347.           is likely to work (correctly or at all) only when the client
  2348.           and server platforms are alike (e.g. both of them are some form
  2349.           of UNIX). Also note that Windows files don't have permissions.
  2350.           Also see [229]FTP CHMOD.
  2351.           
  2352.    SET FTP DATES { ON, OFF }
  2353.           When downloading files with GET or MGET, this tells whether
  2354.           Kermit should try to set the received file's date from the
  2355.           server's date. FTP DATES is OFF by default, for compatibility
  2356.           with other FTP clients, and also because (a) the FTP server
  2357.           might not support file-date inquiries, and (b) FTP protocol
  2358.           does not allow date preservation when uploading. So at best,
  2359.           SET FTP DATES ON can work only when downloading.
  2360.           
  2361.    SET FTP FILENAMES { AUTO, CONVERTED, LITERAL }
  2362.           When uploading (sending) files, this tells whether to convert
  2363.           outbound filenames to "common form". This means allowing only
  2364.           one period in a name, uppercasing any lowercase letters,
  2365.           replacing spaces by underscores, etc. AUTOMATIC is the default,
  2366.           meaning LITERAL when client and server are the same type of
  2367.           system (e.g. UNIX) and CONVERTED otherwise. Special case: if
  2368.           the setting is AUTOMATIC and the client is not UNIX and the
  2369.           server identifies itself as UNIX, Kermit uses a less-strict
  2370.           form of conversion, in which lowercase letters are not
  2371.           uppercased and the filename can contain any number of periods,
  2372.           but spaces are still converted to underscore. When receiving,
  2373.           conversion generally means to change all-uppercase names to
  2374.           lowercase and spaces to underscore.
  2375.           
  2376.    SET FTP UNIQUE-SERVER-NAMES { ON, OFF }
  2377.           Applies only to uploads. Tells the server to create new, unique
  2378.           names for incoming files that have the same names as existing
  2379.           files. OFF by default, in which case the server overwrites
  2380.           existing files with new files of the same name. When ON, the
  2381.           server uses its own built-in method for creating new names for
  2382.           incoming files; for example, appending a period (.) and a
  2383.           number to the name. CAUTION: Use this option only if you do not
  2384.           need to refer to the file after it is uploaded, since FTP
  2385.           protocol provides no mechanism for the client to find out what
  2386.           name was assigned by the server.
  2387.           
  2388.    SET FTP COLLISION { ... }
  2389.           When downloading, what to do if an incoming file has the same
  2390.           name as an existing file. Options are the same as for SET FILE
  2391.           COLLISION. If this command is not given, Kermit's regular FILE
  2392.           COLLISION setting is used. If this command is given, it
  2393.           overrides the FILE COLLISION setting for FTP transfers only.
  2394.           See [230]Section 3.6.2 for details.
  2395.           
  2396.    SET FTP TYPE { TEXT, BINARY, TENEX }
  2397.           Changes the default transfer mode. When sending (uploading)
  2398.           files, this command has no effect unless you disable automatic
  2399.           text/binary mode switching ([231]Section 4) with SET FILE SCAN
  2400.           OFF or SET TRANSFER MODE MANUAL. When receiving (downloading)
  2401.           files, this command establishes the transfer mode to be used
  2402.           when a filename does not match any of Kermit's text or binary
  2403.           filename patterns, unless you use SET FTP
  2404.           GET-FILETYPE-SWITCHING or SET TRANSFER MODE MANUAL to disable
  2405.           automatic switching, in which case, this command establishes
  2406.           the transfer mode for all downloaded files. In all cases,
  2407.           however, the FTP TYPE can be overridden in any GET or PUT
  2408.           command by including a /TEXT (/ASCII), /BINARY, or /TENEX
  2409.           switch. The FTP TYPE is independent of the Kermit FILE TYPE
  2410.           setting. TENEX is used for sending 8-bit binary files to 36-bit
  2411.           platforms such as TOPS-10, TOPS-20, and TENEX, and getting them
  2412.           back again. Synonym: ASCII = TEXT. Note: there is also an FTP
  2413.           TYPE command, which does what SET FTP TYPE does but also sends
  2414.           a TYPE command to the server immediately if the given type is
  2415.           different from the current one.
  2416.           
  2417.    If you want want specific FTP preference settings to be in effect for
  2418.    all your Kermit FTP sessions, put the desired SET FTP commands in your
  2419.    Kermit customization file (~/.mykermrc in UNIX, K95CUSTOM.INI in
  2420.    Windows.
  2421.    
  2422.    [ [232]Top ] [ [233]Contents ] [ [234]C-Kermit Home ] [ [235]Kermit
  2423.    Home ]
  2424.      _________________________________________________________________
  2425.    
  2426.   3.4. Managing Directories and Files
  2427.   
  2428.    In Kermit, commands for directory and file management can refer to:
  2429.    
  2430.      * The local computer
  2431.      * A remote computer when you have a connection to a Kermit server or
  2432.        IKSD.
  2433.      * A remote computer when you have a connection to an FTP server.
  2434.        
  2435.    (There can also be an HTTP connection, but the commands in this
  2436.    section don't apply to HTTP connections.)
  2437.    
  2438.    Thus in general, each such command comes in three forms:
  2439.    
  2440.     1. With no prefix in C-Kermit 8.0.200, it refers to the local
  2441.        computer (CD, DIR, etc). In C-Kermit 8.0.201, however, the "locus"
  2442.        switches to automatically to the remote FTP server when you make
  2443.        an FTP connection (see the SET LOCUS description [236]Section 7);
  2444.        thus C-Kermit 8.0.201 acts almost exactly like a regular FTP
  2445.        client when it has an FTP connection, yet still acts like itself
  2446.        on other kinds of connections.
  2447.     2. With the REMOTE prefix, it is for a Kermit server (REMOTE CD,
  2448.        REMOTE DIR).
  2449.     3. With the FTP prefix, it's for an FTP server (FTP CD, FTP DIR).
  2450.        
  2451.    Note the difference in command format between the Kermit FTP client
  2452.    and most other FTP clients: in Kermit, unprefixed file management
  2453.    commands apply locally; the FTP prefix is required to send them to the
  2454.    server (but see [237]Section 3.8, which explains how "R-commands" can
  2455.    be used when the only connection is an FTP connection, or when you
  2456.    explicitly tell Kermit to "switch focus" to the FTP connection). In
  2457.    most FTP clients, on the other hand, unprefixed commands are for the
  2458.    server, and local commands require a prefix.
  2459.    
  2460.    Kermit's FTP file and directory management commands are as follows.
  2461.    When an R-command is included in the Synonyms list, be sure to read
  2462.    [238]Section 3.8 about rules for use of R-commands.
  2463.    
  2464.    FTP CD [ directory ]
  2465.           Tells the FTP server to change its default (working) directory
  2466.           to the one given, which usually must be expressed in the syntax
  2467.           of the server platform (UNIX, VMS, etc). If the directory is
  2468.           not specified, the result depends on the FTP server -- it might
  2469.           complain that the command is illegal, or it might change to
  2470.           your original login directory. Synonyms: FTP CWD (Change
  2471.           Wording Directory); RCD.
  2472.           
  2473.    FTP CDUP
  2474.           Tells the FTP server to change its default (working) directory
  2475.           to the parent directory of its current one (equivalent to
  2476.           "cd .." in UNIX, or "cd [-]" in VMS). Synonyms: RCDUP, FTP UP.
  2477.           
  2478.    FTP PWD
  2479.           Asks the FTP server to report ("print") its current working
  2480.           directory. Synonym: RPWD.
  2481.           
  2482.    FTP MKDIR directory
  2483.           Asks the FTP server to create the directory whose name is
  2484.           given. In general, the name must be in the syntax of the
  2485.           server's file system, and it must be either absolute (a full
  2486.           pathname) or relative to the server's current (working)
  2487.           directory. This command fails if the directory can't be created
  2488.           for any reason, including that it exists already. Synonym:
  2489.           RMKDIR.
  2490.           
  2491.    FTP RMDIR directory
  2492.           Asks the FTP server to remove the directory whose name is
  2493.           given. The rules are the same as for MKDIR, plus in most cases,
  2494.           the server will not remove any directory unless it is empty.
  2495.           Synonym: RRMDIR.
  2496.           
  2497.    FTP DIRECTORY [ filespec ] [ redirectors ]
  2498.           Tells the FTP server to send a directory listing of the
  2499.           specified files. If no filespec is given, the server lists all
  2500.           files in its current working directory. The results are in
  2501.           whatever format the server chooses to send them. You can use
  2502.           UNIX-line redirectors to send the listing to a file or a
  2503.           pipeline, exactly as with the regular Kermit client/server
  2504.           REMOTE DIRECTORY command ([239]Using C-Kermit, Chapter 11).
  2505.           Synonym: RDIRECTORY. Examples:
  2506.           
  2507.     ftp dir                           ; Show listing of all files on screen
  2508.     ftp dir *.txt                     ; List *.txt files on screen
  2509.     ftp dir *.txt > somefile          ; Put listing in somefile
  2510.     ftp dir *.txt >> somefile         ; Append listing to somefile
  2511.     ftp dir *.txt | sort > somefile   ; Put sorted listing in somefile
  2512.     ftp dir | more                    ; Runs list through "more"
  2513.     ftp dir | sort | more             ; Runs list through "sort" and "more"
  2514.  
  2515.    FTP VDIRECTORY [ filespec ] [ redirectors ]
  2516.           "Verbose" directory. This is an alternative FTP DIRECTORY
  2517.           command primarily for use with DECSYSTEM-20 (TOPS-20) FTP
  2518.           servers, which send only filenames when given a DIRECTORY
  2519.           command; the VDIRECTORY command makes them also send file
  2520.           sizes, dates, and attributes.
  2521.           
  2522.    FTP CHECK filespec
  2523.           Asks the FTP server whether the given file exists or, if the
  2524.           filespec contains wildcards, if any files match, and this
  2525.           command succeeds or fails accordingly.
  2526.           
  2527.    FTP MODTIME filename
  2528.           Asks the FTP server, via the not-yet-standard FTP MDTM command,
  2529.           to send the modification date and time of the given file. The
  2530.           response should be a numeric string in the format:
  2531.           yyyymmddhhmmssxxxxx... where yyyy is the year, mm is the month,
  2532.           dd is the day, hh is the hour (0-23), mm is the minute, ss is
  2533.           the second, and xxx... is the optional fraction of the second
  2534.           (0 or more digits). The date and time is expressed in UTC (GMT,
  2535.           Zulu, Zero-Meridian). The result is available programmatically
  2536.           in the [240]\v(ftp_message) variable, and is understandable by
  2537.           Kermit's date-time switches and functions. For example, suppose
  2538.           we want to upload all local files that are newer than a
  2539.           particular file on the server:
  2540.           
  2541.   C-Kermit> ftp modtime signpost
  2542.   C-Kermit> echo \v(ftp_message)
  2543.   20010807113542.014
  2544.   C-Kermit> ftp mput /after:\v(ftp_message)GMT *
  2545.  
  2546.           Note that we must append "GMT" to the date-time string to let
  2547.           the /AFTER switch know the time is GMT rather than local.
  2548.           
  2549.    FTP SIZE filename
  2550.           Asks the FTP server to send the size (in bytes) of the given
  2551.           file. The result might vary depending on whether the current
  2552.           FTP TYPE is binary or text ("ascii"). For a reliable byte
  2553.           count, do FTP TYPE BINARY first. The result is available
  2554.           programmatically in the [241]\v(ftp_message) variable.
  2555.           
  2556.    FTP CHMOD permissions filename
  2557.           Tells the FTP server to set the permissions (protection) of the
  2558.           given file to the ones given. The permissions and filename must
  2559.           be given in whatever syntax is required by the server. Example
  2560.           (for a UNIX-based FTP server):
  2561.           
  2562.   ftp chmod 664 oofa.txt
  2563.  
  2564.           Not all servers support this command. For non-UNIX-based
  2565.           servers, you might need to use FTP QUOTE or FTP SITE and the
  2566.           appropriate platform-specific FTP server command.
  2567.           
  2568.    FTP UMASK [ number ]
  2569.           This command is probably specific to UNIX-based servers; it
  2570.           sets the UNIX "umask", which is the default permissions mask
  2571.           for new (in this case, incoming) files. Crudely put, the UNIX
  2572.           umask is an octal representation of a binary number in in which
  2573.           a 1 bit stands for a permission bit that must be 0, and a 0 bit
  2574.           stands for a permission bit that can be 0 or 1 depending on
  2575.           other factors, such as the permissions of the parent directory.
  2576.           Example: "umask 007" requires that new files are created
  2577.           without read/write/execute world permission. If the number is
  2578.           not specified, the server's current umask is reported.
  2579.           
  2580.    FTP RENAME filename newname
  2581.           Asks the FTP server to rename the file whose name is "filename"
  2582.           to "newname". Works only for one file; can not be used with
  2583.           wildcards. The server's interpretation of "newname" can vary
  2584.           (in some cases it must be a filename, in others perhaps it can
  2585.           also be a directory name, in which case if the filename denote
  2586.           a regular file, the file might be moved to the given
  2587.           directory). Some servers might allow files to be renamed
  2588.           ("moved") between physical disks or partitions, others might
  2589.           not. Synonym: RRENAME.
  2590.           
  2591.    FTP DELETE [ switches ] filespec [ filespec [ ... ] ]
  2592.           Tells the FTP server to delete the file or files listed. Each
  2593.           file specification may, but need not, contain wildcard
  2594.           characters to match multiple files. File specifications and
  2595.           wildcard syntax must be those of the server. Any file
  2596.           specifications that contain spaces must be enclosed in braces
  2597.           or doublequotes. FTP DELETE switches are:
  2598.           
  2599.  /ERROR-ACTION:  /FILENAMES:     /NOBACKUPFILES  /QUIET
  2600.  /EXCEPT:        /LARGER-THAN:   /NODOTFILES     /NOPAGE
  2601.  /PAGE           /RECURSIVE      /SMALLER-THAN:
  2602.  
  2603.           When used with FTP DELETE, the /RECURSIVE switch deletes files
  2604.           but not directories, and furthermore depends on the server
  2605.           providing recursive file lists, which is not the normal
  2606.           behavior. For further details, see the decriptions of these
  2607.           switches in [242]Section 3.6. Synonyms: FTP MDELETE (Kermit
  2608.           makes no distinction between DELETE and MDELETE); RDELETE.
  2609.           
  2610.    FTP TYPE { TEXT, BINARY, TENEX }
  2611.           Tells the FTP server to change its file-transfer type to the
  2612.           one given, immediately. See [243]SET FTP TYPE for details.
  2613.           
  2614.    [ [244]Top ] [ [245]Contents ] [ [246]C-Kermit Home ] [ [247]Kermit
  2615.    Home ]
  2616.      _________________________________________________________________
  2617.    
  2618.   3.5. Uploading Files With FTP
  2619.   
  2620.    Uploading means sending files from the client (Kermit) to the FTP
  2621.    server. The basic command for uploading files with FTP is PUT:
  2622.    
  2623.    FTP PUT [ switches ] [ filespec [ as-name ] ]
  2624.           Uploads (sends) the file or files that match the file
  2625.           specification, which may include wildcards, to the server. If
  2626.           no filespec is given, the names of files to send are taken from
  2627.           the /LISTFILE: file, if any, otherwise from the SEND-LIST, if
  2628.           any. Unless you go out of your way to prevent it, Kermit
  2629.           determines the transfer mode (text or binary) for each file
  2630.           automatically, and switches automatically on a per-file basis.
  2631.           If an as-name is given, the file is sent under that name
  2632.           instead of its own (if an as-name is given with a wildcard
  2633.           filespec, the result is a bit more complicated, and is
  2634.           explained later in this section).
  2635.           
  2636.    Unlike normal FTP clients, Kermit does not prompt you by default (or
  2637.    at all) for each file; it just sends them, just as it does with Kermit
  2638.    protocol. The filespec can be a literal filename or a Kermit pattern,
  2639.    described in:
  2640.    
  2641.   [248]http://www.columbia.edu/kermit/ckermit70.html#x4.9
  2642.  
  2643.    Kermit patterns are equivalent to C-Shell patterns and provide a fair
  2644.    amount of flexibility in selecting which files to send, which is
  2645.    augmented by the file-selection switches presented in [249]Section
  2646.    3.5.1.
  2647.    
  2648.    FTP MPUT [ switches ] filespec [ filespec [ ... ] ]
  2649.           FTP MPUT is just like FTP PUT except it allows you to give more
  2650.           than one file specification, and it does not allow an as-name
  2651.           in the file list. However, as-names can be given to either PUT
  2652.           or MPUT with the /AS-NAME: switch.
  2653.           
  2654.    If a PUT or MPUT command results in one file being uploaded, it
  2655.    succeeds if the file is uploaded completely and fails otherwise. If
  2656.    more than one file is selected for upload, success or failure depends
  2657.    on the [250]FTP ERROR-ACTION setting; if it is PROCEED (the default
  2658.    setting), then the [M]PUT command succeeds if at least one of the
  2659.    files was completely uploaded, and fails otherwise, If FTP
  2660.    ERROR-ACTION is QUIT, the [M]PUT command succeeds if all selected
  2661.    files were uploaded successfully, and fails if any file failed.
  2662.    
  2663.    FTP uploads may be interrupted just like Kermit uploads. While the
  2664.    transfer is in progress, type:
  2665.    
  2666.   X to interrupt the current file and go on to the next file.
  2667.   Z to cancel the current file and all remaining files.
  2668.   ^C (Control-C): Like Z, but might act more quickly.
  2669.  
  2670.    MPUT may be used as in regular FTP clients, but it is not required to
  2671.    send multiple files; in Kermit it is required only if you want to give
  2672.    multiple file specifications. Examples:
  2673.    
  2674.   ftp put oofa.txt               ; Send a single file oofa.txt
  2675.   ftp put oofa.txt budget.txt    ; Send single file oofa.txt as budget.txt
  2676.   ftp put *.txt                  ; Send all *.txt files
  2677.   ftp mput *.txt                 ; Send all *.txt files (same as "put *.txt")
  2678.   ftp mput *.txt foo.bar         ; Send all *.txt files plus foo.bar
  2679.  
  2680.    The distinction between PUT and MPUT is important only when more than
  2681.    one filespec is given, just like the distinction between Kermit SEND
  2682.    and MSEND:
  2683.    
  2684.   ftp put oofa.txt budget.txt    ; Send oofa.txt AS budget.txt
  2685.   ftp mput oofa.txt budget.txt   ; Send oofa.txt AND budget.txt
  2686.  
  2687.    If the source file specification includes any path segments, for
  2688.    example:
  2689.    
  2690.   put /tmp/oofa.txt
  2691.   put subdir/another/andanother/oofa.txt
  2692.  
  2693.    the path portion is stripped from the filename that is sent to the
  2694.    server. However, if an as-name contains a path, it is retained.
  2695.    Examples:
  2696.    
  2697.   ftp put /usr/doc/oofa.txt      ; Send as "oofa.txt".
  2698.   ftp put oofa.txt /tmp/oofa.txt ; Send as "/tmp/oofa.txt"
  2699.  
  2700.    The latter example sends the file oofa.txt from your current local
  2701.    directory to the server's /tmp directory. This works only if the
  2702.    server uses the same directory notation that you used in the as-name
  2703.    AND the given directory already exists on the server AND if you have
  2704.    write access to it.
  2705.    
  2706.    Use caution when uploading from a case-sensitive file system, such as
  2707.    UNIX, to a file system that is not case sensitive, such as Windows or
  2708.    VMS. If you have two files in UNIX, AA and aa and upload both of them,
  2709.    the second one will overwrite the first. The only way around this
  2710.    provided by FTP protocol is its "unique server names" feature (SET FTP
  2711.    UNIQUE-SERVER-NAMES or the /UNIQUE switch described below).
  2712.      _________________________________________________________________
  2713.    
  2714.     3.5.1. FTP PUT Switches
  2715.     
  2716.    FTP PUT and MPUT are similar in format and behavior to the regular
  2717.    Kermit SEND and MSEND commands, and they allow most of the same
  2718.    optional switches:
  2719.    
  2720. C-Kermit>ftp put ? Filename, or switch, one of the following:
  2721.  /after:                 /larger-than:           /rename-to:
  2722.  /array:                 /listfile:              /server-character-set:
  2723.  /as-name:               /local-character-set:   /server-rename-to:
  2724.  /before:                /move-to:               /simulate
  2725.  /binary                 /nobackupfiles          /smaller-than:
  2726.  /command                /nodotfiles             /tenex
  2727.  /delete                 /nofollowlinks          /text
  2728.  /dotfiles               /not-after:             /transparent
  2729.  /error-action:          /not-before:            /type:
  2730.  /except:                /permissions:           /update
  2731.  /filenames:             /quiet                  /unique-server-names
  2732.  /filter:                /recover
  2733.  /followlinks            /recursive
  2734.  
  2735.    Most of these switches are common to Kermit's SEND and MSEND commands,
  2736.    so are described only briefly here. For greater detail see:
  2737.    
  2738.      [251]http://www.columbia.edu/kermit/ckermit70.html#x1.5 (explanation
  2739.    of switches)
  2740.      [252]http://www.columbia.edu/kermit/ckermit70.html#x4.7
  2741.    (file-transfer switches)
  2742.    
  2743.    First the file-selection switches:
  2744.    
  2745.    /AFTER:date-time
  2746.           
  2747.    /BEFORE:date-time
  2748.           
  2749.    /NOT-AFTER:date-time
  2750.           
  2751.    /NOT-BEFORE:date-time
  2752.           Only send those files modified on or after or before the given
  2753.           date and time. These switches can be combined to select files
  2754.           modified between two date/times. Various date-time formats are
  2755.           accepted; if the date-time contains spaces, it must be enclosed
  2756.           in braces or doublequotes. See
  2757.           [253]http://www.columbia.edu/kermit/ckermit70.html#x1.6 for
  2758.           details about date-time formats. Examples:
  2759.           
  2760.   ftp put /after:{1 jan 2000 0:00:00} *
  2761.   ftp put /after:-5days *
  2762.  
  2763.    /LARGER-THAN:number
  2764.           
  2765.    /SMALLER-THAN:number
  2766.           Only send files larger (smaller) than the given number of bytes
  2767.           (octets). These switches can be combined to select files in a
  2768.           certain size range.
  2769.           
  2770.    /TYPE:{TEXT,BINARY}
  2771.           Only send files that are the given type, which is determined
  2772.           for each file just before sending it by file scanning. BINARY
  2773.           includes TENEX; if you have included a /TENEX switch, or
  2774.           previously given a [SET] FTP TYPE TENEX command, binary files
  2775.           are sent in TENEX, rather than BINARY mode.
  2776.           
  2777.    /[NO]DOTFILES
  2778.           [Don't] include files whose names begin with dot (.). By
  2779.           default, such files are not included unless your filespec
  2780.           explicitly mentions them.
  2781.           
  2782.    /NOBACKUPFILES
  2783.           Don't include files whose names end with .~nnn~, where nnn is a
  2784.           number, e.g. oofa.txt.~27~. These are backup files created by
  2785.           Kermit, EMACS, and other applications. By default, backup files
  2786.           are included.
  2787.           
  2788.    /NOFOLLOWLINKS
  2789.           (UNIX only) Skip over symbolic links rather than following them
  2790.           (default). This applies to wildcard and/or recursive [M]PUTs;
  2791.           if a single filename is given, and it happens to be a symbolic
  2792.           link, the file it points to is sent.
  2793.           
  2794.    /FOLLOWLINKS
  2795.           (UNIX only) Always follow (resolve) symbolic links, even in
  2796.           wildcard or recursive [M]PUTs. Use with caution. Watch out for
  2797.           circular links, endless loops, etc.
  2798.           
  2799.    /EXCEPT:pattern
  2800.           Exception list -- don't send files whose names match the given
  2801.           pattern. See [254]Section 1.5.4 of the [255]C-Kermit 7.0 Update
  2802.           Notes for details. If you want to exclude a directory from a
  2803.           recursive [M]PUT, use /EXCEPT:{dirname/*}.
  2804.           
  2805.    /RECURSIVE
  2806.           Sends the desired files from the current (or given) directory,
  2807.           plus all directories beneath it, including empty directories,
  2808.           replicating the directory structure on the server. No special
  2809.           capabilities are required in the server, but of course your
  2810.           login ID on the server must have the appropriate access and
  2811.           permission to create directories. Recursive PUTs work not only
  2812.           between like platforms (e.g. UNIX to UNIX) but also between
  2813.           unlike ones (e.g. UNIX to VMS or Windows), in which case
  2814.           text-file format differences are handled by Kermit's automatic
  2815.           text/binary mode switching ([256]Section 4) and character-set
  2816.           translation ([257]Section 3.7). Synonym: /SUBDIRECTORIES.
  2817.           
  2818.    /UPDATE
  2819.           Send only files that have changed since last time ([258]Section
  2820.           3.5.2).
  2821.           
  2822.    /ARRAY:arrayname
  2823.           The "file" to be sent is an array, or a segment of one, rather
  2824.           than a real file. In this case the other selection switches
  2825.           don't apply. The array contents are sent in text mode, and each
  2826.           array element is treated as a line. Example:
  2827.           
  2828.  
  2829.   ftp put /as-name:array.txt /array:&a
  2830.  
  2831.    (or, to send a segment of the array, /array:&a[100:199]). If you don't
  2832.           include an /AS-NAME, a name of "_array_x_" is used (where x is
  2833.           the array letter). If you include this switch, most other
  2834.           switches are meaningless and ignored.
  2835.           
  2836.    /COMMAND
  2837.           The "file" to be sent is the standard output of a command,
  2838.           rather than a real file. It is sent in text or binary mode
  2839.           according to the prevailing FTP TYPE, which can be overridden
  2840.           with a /TEXT or /BINARY switch. Example: Example:
  2841.           
  2842.  
  2843.   ftp put /command /as-name:{userlist} {finger | sort -r}
  2844.  
  2845.    /LISTFILE:filename
  2846.           Tells Kermit to obtain the list of files to be sent from the
  2847.           file whose name is given. This file must contain one file
  2848.           specification (which may be wild) per line. If the list
  2849.           includes files from different directories, such as a recursive
  2850.           listing of a directory tree, the paths are recreated on the
  2851.           server (if possible) if you include the /RECURSIVE switch;
  2852.           otherwise all the files are sent to the current directory on
  2853.           the server.
  2854.           
  2855.    Now the other switches:
  2856.    
  2857.    /AS-NAME:text
  2858.           If a single file is being sent, send it with the given text as
  2859.           its name. If multiple files are being sent, the text must be a
  2860.           template that includes variables such as \v(filename),
  2861.           \v(filenumber), \v(ntime), to allow dynamic creation of each
  2862.           name. The same applies to the as-name field of the FTP PUT
  2863.           command. If this switch is not included (and an as-name is not
  2864.           included as the second filename to PUT), each file is sent with
  2865.           its own name.
  2866.           
  2867.    /BINARY
  2868.           
  2869.    /TEXT
  2870.           
  2871.    /TENEX
  2872.           Forces this upload to take place in the given mode, regardless
  2873.           of the current FTP TYPE setting, and without automatic
  2874.           text/binary switching. /ASCII is a synonym for /TEXT.
  2875.           
  2876.    /FILTER:command
  2877.           Specifies that the file(s) is/are to be passed through the
  2878.           given command or pipeline on their way to the server. Example:
  2879.           
  2880.   ftp put /binary /filter:{gzip -c \v(filename)} /as-name:\v(filename).gz *
  2881.  
  2882.    /TRANSPARENT
  2883.           
  2884.    /LOCAL-CHARACTER-SET:name
  2885.           
  2886.    /SERVER-CHARACTER-SET:name
  2887.           Character-set translation for text files, explained in
  2888.           [259]Section 3.7.
  2889.           
  2890.    /ERROR-ACTION:{PROCEED,QUIT}
  2891.           Overrides the prevailing [260]FTP ERROR-ACTION for the duration
  2892.           of this PUT or MPUT command only.
  2893.           
  2894.    /RECOVER
  2895.           Resume an interrupted transfer where from the point of
  2896.           interruption (explained in [261]Section 3.5.2). Synonym:
  2897.           /RESTART.
  2898.           
  2899.    /DELETE
  2900.           Tells Kermit to delete each source file immediately after, and
  2901.           only if, it has been uploaded completely and successfully.
  2902.           This, in effect, moves the file from the client to the server.
  2903.           
  2904.    /MOVE-TO:directory
  2905.           Tells Kermit to move each source file to the named local
  2906.           directory after, and only if, it has been uploaded completely
  2907.           and successfully.
  2908.           
  2909.    /RENAME-TO:template
  2910.           Tells Kermit to rename each (local) source file according to
  2911.           the given template after, and only if, it has been uploaded
  2912.           completely and successfully. The template works as in /AS-NAME.
  2913.           
  2914.    /SERVER-RENAME-TO:template
  2915.           Tells Kermit to ask the server to rename each file according to
  2916.           the given template as soon as, and only if, it has been
  2917.           received completely and successfully. The template works as in
  2918.           /AS-NAME. Requires write and rename access on the server, so
  2919.           doesn't usually work with (e.g.) anonymous uploads to public
  2920.           incoming areas where the permissions don't allow renaming.
  2921.           Examples:
  2922.           
  2923.         ftp mput /server-rename:\v(filename).ok *
  2924.                 Appends ".ok" to each filename on the server when it's
  2925.                 finished uploading.
  2926.                 
  2927.         ftp mput /as-name:\v(filename).tmp /server-rename:\v(filename) *
  2928.                 This is the reverse of the previous example; it uses a
  2929.                 temporary name while uploading is in progress and reverts
  2930.                 the file to its real name when uploading is complete.
  2931.                 
  2932.         ftp mput /as-name:\v(filename)
  2933.                 /server-rename:../final/\v(filename) *
  2934.                 Moves the file from the working directory to a final
  2935.                 directory when the upload is complete, but in this case
  2936.                 you have to know the pathname syntax of the server. If
  2937.                 the rename fails, the [M]PUT command fails according to
  2938.                 the [262]FTP ERROR-ACTION selection.
  2939.                 
  2940.    /FILENAMES:{AUTOMATIC,CONVERTED,LITERAL}
  2941.           Overrides the [263]FTP FILENAMES setting for this upload only.
  2942.           
  2943.    /PERMISSIONS:{ON,OFF}
  2944.           Overrides the [264]FTP PERMISSIONS setting for this upload
  2945.           only.
  2946.           
  2947.    /UNIQUE
  2948.           Tells Kermit to tell the server to give [265]unique names to
  2949.           incoming files that would otherwise overwrite existing files
  2950.           that have the same name. This switch conflicts with /UPDATE,
  2951.           /RECOVER, /PERMISSIONS, and /SERVER-RENAME since the client has
  2952.           no way of knowing the name assigned by the server.
  2953.           
  2954.    /QUIET
  2955.           Don't display file-transfer progress or statistics.
  2956.           
  2957.    /SIMULATE
  2958.           Shows which files would be sent without actually sending them.
  2959.           Useful (for example) with /UPDATE (next section). The results
  2960.           are shown in the file-transfer display (if it is not disabled)
  2961.           and in the transaction log (if one is active). Hint: use SET
  2962.           TRANSFER DISPLAY BRIEF.
  2963.      _________________________________________________________________
  2964.    
  2965.     3.5.2. Update Mode
  2966.     
  2967.    When you include the /UPDATE switch, this means to skip sending any
  2968.    file that already exists on the server if the local file's
  2969.    modification date/time is not later than that of the corresponding
  2970.    file on the server. Here is a typical application for update mode:
  2971.    Suppose that on Computer A, you maintain a large set of files (say, a
  2972.    collection of Web pages and graphics images, or the source files for a
  2973.    software application), and you need to keep a parallel copy on another
  2974.    Computer, B. Of course you could upload the entire collection every
  2975.    day:
  2976.    
  2977.   cd source-directory
  2978.   ftp computerb.xyzcorp.com
  2979.   ( authentication details... )
  2980.   ftp cd target-directory
  2981.   ftp put [ switches ] *
  2982.  
  2983.    But if the total size is large or the network slow, this would be
  2984.    unnecessarily time-consuming. Worse, if other users or sites had to
  2985.    update whenever new files appeared in B's directory, this would cause
  2986.    them unnecessary work. By including the /UPDATE switch:
  2987.    
  2988.   ftp put /update [ other-switches ] *
  2989.  
  2990.    only those files that changed since last time are uploaded. Here's how
  2991.    it works. For each local file that is selected for uploading:
  2992.    
  2993.      * The remote filename is determined in the normal way, according to
  2994.        the [266]FTP FILENAMES setting, /FILENAMES switch, or the as-name,
  2995.        if any.
  2996.      * Kermit sends an MDTM (modification time) command for the
  2997.        corresponding remote filename to the server.
  2998.      * If the server does not understand the MDTM command, the file is
  2999.        sent.
  3000.      * If the server can't find a file with the given name, the file is
  3001.        sent.
  3002.      * If the local file's modification time is later than that of the
  3003.        remote file, the file is sent.
  3004.      * Otherwise -- the remote file exists but its modification time is
  3005.        equal to or earlier than that of the local file -- the file is
  3006.        skipped.
  3007.        
  3008.    All time comparisons take place in Coordinated Universal Time
  3009.    (UTC)([267]1), also known as GMT or Zulu time: Timezone 0; standard
  3010.    time, without daylight savings.
  3011.    
  3012.      WARNING: Some FTP servers, such as Novell NWFTPD.NLM, ignore or
  3013.      misimplement the FTP specification and send local time rather than
  3014.      UTC.
  3015.      
  3016.    Update mode is useful only when always used in the same direction.
  3017.    When you transfer a file with FTP, the destination file receives the
  3018.    current timestamp on the receiving computer, not the original file's
  3019.    timestamp ([268]2). If you try to FTP PUT /UPDATE the same file again,
  3020.    it will be skipped (as expected) since the remote copy is newer.
  3021.    However, if you try to FTP GET /UPDATE the same file ([269]Section
  3022.    3.6), it will be transferred for the same reason.
  3023.    
  3024.    To check the availability of PUT /UPDATE on a particular connection,
  3025.    issue an FTP MODTIME command for a file that is known to exist on the
  3026.    server. If it succeeds, PUT /UPDATE should work and in that case, you
  3027.    can run a procedure like the one above every day: the first time, it
  3028.    sends all the files; after that, it sends only the ones that changed.
  3029.    If a transaction log is active, a notation is included for any files
  3030.    that are skipped.
  3031.    
  3032.    Notes:
  3033.     1. Why is Coordinated Universal Time abbreviated UTC? From the
  3034.        [270]National Institute of Standards and Technology FAQ: "In 1970
  3035.        the Coordinated Universal Time system was devised by an
  3036.        international advisory group of technical experts within the
  3037.        International Telecommunication Union (ITU). The ITU felt it was
  3038.        best to designate a single abbreviation for use in all languages
  3039.        in order to minimize confusion. Since unanimous agreement could
  3040.        not be achieved on using either the English word order, CUT, or
  3041.        the French word order, TUC, the acronym UTC was chosen as a
  3042.        compromise."
  3043.     2. The Kermit FTP client is unusual in that, when downloading only,
  3044.        it can set the received file's date from the file's date on the
  3045.        server, but this should not affect the update feature.
  3046.      _________________________________________________________________
  3047.    
  3048.     3.5.3 Recovery
  3049.     
  3050.    Suppose that while you are uploading a large file over a slow
  3051.    connection, the connection is lost before the entire file is
  3052.    transferred. With most FTP clients, you would have to start over, thus
  3053.    resending the portion of the file that was sent already, and that is
  3054.    already on the server. But Kermit's /RECOVER switch (Synonym:
  3055.    /RESTART) lets you continue an interrupted transfer from the point of
  3056.    failure, thus transferring only the part that wasn't sent already. The
  3057.    prerequisites for recovery are:
  3058.    
  3059.      * The transfer must be in BINARY mode, or else the client and server
  3060.        must reside on like systems (e.g. both on some form of UNIX).
  3061.      * The FTP server must support the SIZE command.
  3062.        
  3063.    Here's how it works. When you include the /RECOVER switch:
  3064.    
  3065.      * Kermit checks for conflicting switches, such as /UPDATE and
  3066.        /UNIQUE; if /RECOVER is given with these switches an error occurs.
  3067.        If /RECOVER is given in other circumstances where it could serve
  3068.        no useful purpose (e.g. with arrays, pipes, or filters), it is
  3069.        ignored.
  3070.        
  3071.    If the switch is accepted, then for each selected file:
  3072.    
  3073.      * If it is not binary (determined by scanning) and the client and
  3074.        server are not on like platforms, recovery is canceled (the entire
  3075.        file is sent). Otherwise:
  3076.      * A SIZE command is sent for the file (using its remote name). If
  3077.        the reply indicates the file was not found, or the SIZE command
  3078.        was not understood, or any other kind of error, recovery is
  3079.        canceled. Otherwise:
  3080.      * A MDTM (modification time) command is sent for the file. If a
  3081.        valid reply is received, and the modification time of the local
  3082.        file is later than that of the remote file, recovery is canceled.
  3083.        Otherwise:
  3084.      * If the sizes of the two files are identical, the file is not sent.
  3085.        Otherwise:
  3086.      * Kermit seeks to the recovery spot in the local file, tells the
  3087.        server to APPEND the data which is about to arrive to the remote
  3088.        file, and then sends the data starting at the recovery point.
  3089.        
  3090.    To safeguard file integrity, recovery is not attempted unless all the
  3091.    preconditions are met. For the widest possible usefulness, APPEND is
  3092.    used rather than RESTART. For stream transfers (the only kind that
  3093.    Kermit supports) the results are the same.
  3094.    
  3095.    By design, the /RECOVER switch can be included with any FTP PUT or
  3096.    MPUT command, even if it specifies a group of files. This allows you
  3097.    to resume an interrupted batch transfer from where it left off. The
  3098.    files that were already completely sent are skipped, the file that was
  3099.    interrupted is recovered, and the remaining files are uploaded.
  3100.    
  3101.    By the way, it doesn't matter how the original partial file was
  3102.    uploaded -- FTP, Kermit, Zmodem, etc: as long as the preconditions are
  3103.    met, it can be recovered with FTP PUT /RECOVER, or for that matter
  3104.    also using Kermit protocol and SEND /RECOVER.
  3105.    
  3106.    A word of caution, however, when the original upload was in text mode
  3107.    with character-set translation ([271]Section 3.7):
  3108.    
  3109.      * If the original upload involved a translation from one single-byte
  3110.        character set to another (e.g. Code Page 850 to Latin-1), recovery
  3111.        is safe if you specify the same translations for the recovery. If
  3112.        you don't, the resulting file will contain a mixture of character
  3113.        sets.
  3114.      * If the original upload involved a translation that changed the
  3115.        size of the file (e.g. from an alphabetic Code Page or Latin
  3116.        Alphabet to Unicode, or vice versa), recovery is NOT safe, even if
  3117.        you specify the same translations.
  3118.        
  3119.    Kermit has no way of knowing anything about the previous upload. As a
  3120.    safeguard, an error occurs if you include /RECOVER and also specify a
  3121.    character-set of UCS2 or UTF8, since recovery can't possibly work in
  3122.    that situation. Otherwise, it's up to you to avoid unsafe recovery
  3123.    operations.
  3124.    
  3125.    [ [272]Top ] [ [273]Contents ] [ [274]C-Kermit Home ] [ [275]Kermit
  3126.    Home ]
  3127.      _________________________________________________________________
  3128.    
  3129.   3.6. Downloading Files With FTP
  3130.   
  3131.    Although uploading files with Kermit's FTP client is just as easy and
  3132.    flexible as sending files with Kermit protocol, the same is not always
  3133.    true for downloading because FTP servers lack some of the capabilities
  3134.    of a Kermit server:
  3135.    
  3136.      * If you want to get more than one file, you have to use MGET, not
  3137.        GET, since the underlying FTP protocol is different in the two
  3138.        cases. Kermit can't "autodetect" which one you mean, as it can
  3139.        with PUT and MPUT, since it can't be expected to know the wildcard
  3140.        syntax of the remote platform and/or FTP server (the same is true
  3141.        for all other FTP clients).
  3142.      * Automatic text-binary mode switching is not done by the server. It
  3143.        can be done by the client (Kermit), but in this case it is not
  3144.        based on a file scan (since there is no way for Kermit prescan a
  3145.        server file), but rather on the filename, using C-Kermit 7.0
  3146.        [276]filename patterns.
  3147.      * Some options that are available with FTP PUT can not be used with
  3148.        FTP [M]GET or don't work the same way:
  3149.          /PERMISSIONS (FTP protocol has no mechanism for this).
  3150.          /[NOT-]BEFORE, /[NOT-]AFTER (because of the timezone problem).
  3151.          /RECOVER works only in binary mode.   /RECURSIVE has limited
  3152.        utility.
  3153.        
  3154.    The commands for downloading are:
  3155.    
  3156.    SET FILE DOWNLOAD-DIRECTORY [ directory ]
  3157.           As with Kermit transfers, this command, if given, tells
  3158.           C-Kermit where to store incoming files in the absence of a
  3159.           specific as-name. If not given, incoming files are stored as
  3160.           indicated by the as-name, if any, otherwise in the current
  3161.           directory, just as with Kermit transfers. The more verbose
  3162.           transfer display formats give the full pathname of each
  3163.           received file, and, in case you have trouble finding a
  3164.           downloaded file afterwards, its full path is also listed in the
  3165.           transaction log (if you kept one), and you can also ask Kermit
  3166.           where it went with the [277]WHERE command.
  3167.           
  3168.    SET FTP GET-FILETYPE-SWITCHING { ON, OFF }
  3169.           ON by default, causing Kermit to switch automatically into text
  3170.           or binary mode for each file based on whether its name matches
  3171.           a text pattern or binary pattern. Set this OFF, or use a /TEXT,
  3172.           /BINARY, or /TENEX switch to defeat this feature. Use SHOW
  3173.           PATTERNS to see the current pattern list.
  3174.           
  3175.    [ FTP ] GET [ switches ] filename [ as-name ]
  3176.           Asks the server to send the given file, and if it comes, stores
  3177.           it locally under the given as-name, if any, otherwise under its
  3178.           original name (modified according to the selected filename
  3179.           conversion option), in your download directory, if you have
  3180.           specified one, otherwise in the directory indicated in the
  3181.           as-name, if any, otherwise in your current directory. If you
  3182.           accidentally use a wildcard in the filename ("get *.txt") the
  3183.           server will reply with a message like "File not found" (unless
  3184.           there is a file whose name actually is "*.txt"). If FTP
  3185.           GET-FILETYPE-SWITCHING is ON, and in the absence of any GET
  3186.           switches to override it, the file is transferred in binary mode
  3187.           if it matches any of Kermit's binary name patterns, and in text
  3188.           mode if it matches any of Kermit's text name patterns, and in
  3189.           the prevailing FTP TYPE if it matches none of these patterns.
  3190.           
  3191.    [ FTP ] MGET [ switches ] filespec [ filespec [ filespec [ ... ] ] ]
  3192.           Like GET, but for multiple files. One or more file
  3193.           specifications can be given, and any or all (or none) of them
  3194.           can contain wildcards. The file list may not include an
  3195.           as-name, but you can still give one with /AS-NAME:.
  3196.           
  3197.    In both the FTP GET and MGET commands, any filenames that contain
  3198.    spaces must be enclosed in braces or doublequotes (see [278]Section 5
  3199.    for details).
  3200.    
  3201.    FTP downloads may be interrupted just like Kermit transfers. While the
  3202.    transfer is in progress, type:
  3203.    
  3204.      * X to interrupt the current file and go on to the next file.
  3205.      * Z (or Control-C) to cancel the current file and all remaining
  3206.        files.
  3207.        
  3208.    Before proceeding, a brief word about temporary files. In FTP
  3209.    protocol, the MGET command works by requesting a file list from the
  3210.    server, and then (internally) issuing a GET command for each file. The
  3211.    file list returned by the server can be any size at all, so in case it
  3212.    is huge, we don't store it in memory; instead we put it in a temporary
  3213.    file. For troubleshooting purposes, you should be aware of two points:
  3214.    
  3215.     1. The location of the temporary file is chosen according the TMP or
  3216.        TEMP environment variables. If neither of these variables is
  3217.        defined, you might need to define it. In case there is not enough
  3218.        space on the indicated disk or partition for the server's file
  3219.        list, you might need to either clean up the temporary area, or
  3220.        redefine the environment variable to indicate a different area
  3221.        that has sufficient space.
  3222.     2. If you want to look at the list yourself, use SET FTP DEBUG ON.
  3223.        This tells Kermit to (a) give you the full pathname of the
  3224.        temporary file at the end of each MGET command, and (b) not to
  3225.        delete it, as it normally does.
  3226.      _________________________________________________________________
  3227.    
  3228.     3.6.1. FTP GET Switches
  3229.     
  3230.    The following switches are available with FTP GET and MGET:
  3231.    
  3232.    /TEXT
  3233.           Specifies a text-mode transfer. Overrides the global FTP TYPE
  3234.           setting for the duration of the current command only. All files
  3235.           are downloaded in text mode. Synonym: /ASCII.
  3236.           
  3237.    /BINARY
  3238.           Specifies a binary-mode transfer. Overrides the global FTP TYPE
  3239.           setting for the duration of the current command only. All files
  3240.           are downloaded in binary mode.
  3241.           
  3242.    /TENEX
  3243.           Specifies a special binary transfer mode to be used when
  3244.           getting 8-bit binary files from a 36-bit platform such as
  3245.           TOPS-10, TOPS-20, or TENEX. Overrides the global FTP TYPE
  3246.           setting for the duration of the current command only. All files
  3247.           are downloaded in the special binary mode.
  3248.           
  3249.    /RECOVER
  3250.           This instructs Kermit to try to recover an incomplete download
  3251.           from the point of failure. Works only in binary mode, and only
  3252.           if the server supports the (not-yet-standard) FTP "REST"
  3253.           command. See [279]Section 3.6.3 for details. Synonym: /RESTART.
  3254.           
  3255.    /FILENAMES:{CONVERTED,LITERAL}
  3256.           Overrides the [280]FTP FILENAMES (filename conversion) setting
  3257.           for this download only.
  3258.           
  3259.    /AS-NAME:text
  3260.           For GET, this is equivalent to giving an as-name after the
  3261.           filename. For MGET, this is the only way to specify alternative
  3262.           names for the incoming files. With MGET, the /AS-NAME text
  3263.           should (must) contain a Kermit variable, usually \v(filename)
  3264.           or \v(filenumber). Example:
  3265.           
  3266.   mget /text /as-name:\v(filename).new *.c
  3267.  
  3268.           This gets all ".c" files and stores them with "
  3269.           
  3270.           .new" appended to their names. See the [281]C-Kermit 7.0 Update
  3271.           Notes for details.
  3272.           
  3273.    /COMMAND
  3274.           This specifies that the incoming file is to be written to the
  3275.           standard input of a command, rather than to a file. The command
  3276.           name is the as-name from the GET command or the /AS-NAME
  3277.           argument. If you need to refer to the incoming file's name in
  3278.           the command, use \v(filename). See the description of the
  3279.           regular Kermit [282]GET /COMMAND command for details and
  3280.           examples.
  3281.           
  3282.    /QUIET
  3283.           Transfer the files quietly; don't put up a file-transfer
  3284.           display.
  3285.           
  3286.    /ERROR-ACTION:{QUIT,PROCEED}
  3287.           This switch affects only MGET. If an error occurs with a
  3288.           particular file, this tells whether to go on to the next file
  3289.           (PROCEED) or to stop right away and fail (QUIT). The default is
  3290.           PROCEED.
  3291.           
  3292.    The file selection switches are:
  3293.    
  3294.    /EXCEPT:{pattern} or /EXCEPT:{{pattern}{pattern}{...}}
  3295.           Exception list for MGET; skip downloading any file whose name
  3296.           matches any of the given patterns (when using the second
  3297.           format, up to 8 patterns may be specified). [283]CLICK HERE for
  3298.           syntax details.
  3299.           
  3300.    /SMALLER-THAN:number
  3301.           Download only files whose size is smaller than the given number
  3302.           of bytes (octets). Requires that the FTP server support the
  3303.           SIZE command.
  3304.           
  3305.    /LARGER-THAN:number
  3306.           Download only files whose size is greater than the given number
  3307.           of bytes. Requires that the FTP server support the SIZE
  3308.           command.
  3309.           
  3310.    /NOBACKUPFILES
  3311.           During MGET, don't download any files whose names end with
  3312.           backup suffixes (.~n~ where n is a number).
  3313.           
  3314.    /NODOTFILES
  3315.           During MGET, don't download any files whose names begin with
  3316.           period (.). Equivalent to /EXCEPT:{.*}.
  3317.           
  3318.    /LISTFILE:local-filename
  3319.           The given file contains a list of files to GET, one per line.
  3320.           Filenames in the listfile can contain wildcard characters in
  3321.           the syntax of the server. There is no limit on the number of
  3322.           lines in the listfile.
  3323.           
  3324.    /NAMELIST:local-filename
  3325.           If this switch is given, then instead of actually retrieving
  3326.           the selected files, the GET command retrieves a list of the
  3327.           names of the files that would be retrieved, and places it in
  3328.           the specifed file. The resulting file is an ordinary text file,
  3329.           with one filename per line, suitable for reading by a person,
  3330.           or processing by a computer program, including Kermit itself
  3331.           (FOPEN / FREAD / FWRITE / FCLOSE), and as /FILELIST: file. If
  3332.           the filename is omitted or given as "-" (dash, hyphen), the
  3333.           list goes to the screen. NOTE: if you want a copy of the
  3334.           complete list sent by the server, use SET FTP DEBUG ON, perform
  3335.           an MGET, and the temporary file containing the list will be
  3336.           kept rather than deleted (and Kermit tells you its name).
  3337.           
  3338.    /UPDATE, /COLLISION:keyword
  3339.           Explained in [284]Section 3.6.2.
  3340.           
  3341.    /RECURSIVE
  3342.           This means to try to download an entire directory tree, rather
  3343.           than just files from a particular directory. In fact, FTP
  3344.           protocol does not provide a method to request a recursive
  3345.           download, so this works only if the FTP server does it anyway,
  3346.           without being asked. In this case, Kermit detects that names in
  3347.           the returned file list contain directory separators, and
  3348.           therefore attempts to create the needed directories as the
  3349.           files arrive. But this can work only if the server is on the
  3350.           same kind of platform as the client, so the pathname syntax can
  3351.           be recognized, and also because the server does not switch
  3352.           between text and binary mode, which would be vital for
  3353.           cross-platform transfers. Use with caution. Synonym:
  3354.           /SUBDIRECTORIES.
  3355.           
  3356.    The FTP protocol does not include explicit mechanisms for recursion,
  3357.    so Kermit builds upon what is available. Although an Internet draft
  3358.    describes a mechanism ("MLST") that would allow protocol-driven
  3359.    recursion, similar to Kermit's File Attribute packets (circa 1984), it
  3360.    has not yet attained RFC or standard status, and servers are not yet
  3361.    widely available that offer this feature. In the meantime, the
  3362.    effectiveness of MGET /RECURSIVE depends on the FTP server
  3363.    implementation. If the server returns a recursive list in response to
  3364.    the standard NLST command (whose behavior is ill-defined), Kermit's
  3365.    FTP GET /RECURSIVE command uses it to re-create the remote directory
  3366.    tree locally. When MLST becomes standardized, the Kermit FTP client
  3367.    will be updated to use it.
  3368.    
  3369.    The /BEFORE:, /AFTER:, /NOT-BEFORE:, and /NOT-AFTER: switches are not
  3370.    available for downloading because of the confusion with timezones.
  3371.    Would the given times be in the local timezone, the server's timezone,
  3372.    or GMT? The FTP server's directory listings show its own local times
  3373.    but since we don't know what timezone the server is in, there's no way
  3374.    to reconcile our local times with the server's. Similarly,
  3375.    /PERMISSIONS can't be preserved in downloads because FTP protocol
  3376.    provides no means of querying the server for a file's permission.
  3377.    
  3378.    Source-file disposition switches:
  3379.    
  3380.    /DELETE
  3381.           Each file that is downloaded successfully is to be deleted from
  3382.           the server. Requires the appropriate file access rights on the
  3383.           server.
  3384.           
  3385.    /SERVER-RENAME-TO:template
  3386.           Asks the server to rename each (remote) source file immediately
  3387.           after, and only if, it is sent correctly. See [285]PUT
  3388.           /SERVER-RENAME-TO: for details.
  3389.           
  3390.    Destination-file disposition switches:
  3391.    
  3392.    /TO-SCREEN
  3393.           Displays the incoming file on the screen rather than storing it
  3394.           on disk. If this switch is given, the /RENAME-TO and /MOVE-TO
  3395.           switches are ignored, the file-transfer display is suppressed,
  3396.           and the given file(s) is/are shown on the screen. Can be used
  3397.           with /FILTER, e.g.
  3398.           
  3399.   get /text /to-screen /filter:more oofa.txt
  3400.  
  3401.           In fact, you should always use /TO-SCREEN with /FILTER or
  3402.           /COMMAND when the command would result in displaying the
  3403.           incoming file on the screen; otherwise C-Kermit would have no
  3404.           way of knowing to suppress its file transfer display (since it
  3405.           can't be expected to know what the command or filter does).
  3406.           
  3407.    /RENAME-TO:template
  3408.           Each file that is downloaded is to be renamed as indicated if
  3409.           and only if it was received completely and without error. The
  3410.           template can be literal text or can contain variables that are
  3411.           evaluated for each file. For MGET, the text must contain
  3412.           variables; for GET it can be a literal string. The \v(filename)
  3413.           variable contains the name of the current file, so:
  3414.           
  3415.   ftp mget /rename-to:\v(filename).ok *
  3416.  
  3417.           causes each file that is successfully downloaded to have ".ok"
  3418.           appended to its name. For details see [286]Section 4.1 of the
  3419.           [287]C-Kermit 7.0 Update Notes.
  3420.           
  3421.    /MOVE-TO:text
  3422.           Just like /RENAME-TO:, except the text denotes the name of a
  3423.           directory to which successfully downloaded files are to be
  3424.           moved. If the directory does not exist, it is created.
  3425.           
  3426.    The file transfer display does not show the /MOVE-TO or /RENAME-TO
  3427.    value, since the incoming file has not yet been moved or renamed.
  3428.      _________________________________________________________________
  3429.    
  3430.     3.6.2. Filename Collisions
  3431.     
  3432.    What should happen if an incoming file has the same name as an
  3433.    existing file in the same directory? By default, Kermit's FILE
  3434.    COLLISION setting applies: BACKUP, RENAME, UPDATE, DISCARD, etc, as
  3435.    described in [288]Using C-Kermit. Kermit's default FILE COLLISION
  3436.    setting is BACKUP (rename the existing file and store the incoming
  3437.    file under its own name) and therefore this is also the default FTP
  3438.    collision action.
  3439.    
  3440.    The name under which an incoming file is to be stored is determined as
  3441.    follows:
  3442.    
  3443.      * If an as-name was given, the as-name is used. Otherwise:
  3444.      * If the client and server platforms are alike or [289]FTP FILENAMES
  3445.        is set to LITERAL (or the /FILENAMES:LITERAL switch was given for
  3446.        this download), the incoming filename is used literally.
  3447.        Otherwise:
  3448.      * The incoming filename is converted to a form that is friendly to
  3449.        the local platform. For UNIX, for example, incoming filenames that
  3450.        are all uppercase (as they might be from, say, VMS or an IBM
  3451.        mainframe) are converted to lowercase.
  3452.        
  3453.    If the resulting name coincides with the name of a local file that
  3454.    already exists, we have a filename collision. Collisions are handled
  3455.    according to the currently selected collision action:
  3456.    
  3457.    SET FTP COLLISION { BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE
  3458.           }
  3459.           This establishes a filename collision for FTP, separate from
  3460.           the Kermit one. The initial FTP collision setting is inherited
  3461.           from Kermit's FILE COLLISION setting when the first FTP command
  3462.           is given, but subsequent changes to Kermit's FILE COLLISION
  3463.           setting do not affect the FTP COLLISION setting. SHOW FTP tells
  3464.           the current FTP COLLISION setting.
  3465.           
  3466.    FTP GET /COLLISION:{BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE}
  3467.           Overrides the current FTP COLLISION action for this download
  3468.           only.
  3469.           
  3470.    FTP GET /UPDATE
  3471.           This is equivalent to GET /COLLISION:UPDATE, and is included
  3472.           for symmetry with PUT /UPDATE
  3473.           
  3474.    FTP GET /UPDATE and /COLLISION:UPDATE mean to download only those
  3475.    files whose modification dates on the server are later than those on
  3476.    the client. Date-time comparisons are done in Coordinated Universal
  3477.    Time (UTC, GMT, ZULU).
  3478.    
  3479.    As when uploading, update mode is effective only when used
  3480.    consistently in one direction. When you download a file with FTP, the
  3481.    local file receives the current timestamp, not the original file's
  3482.    timestamp. If you try to FTP GET /UPDATE the same file again, it is
  3483.    skipped (as expected) since the local copy is newer. However, if you
  3484.    try to FTP PUT /UPDATE the same file, it is sent for the same reason.
  3485.    
  3486.    (It might be possible to set the downloaded file's date from the
  3487.    server file's date but (a) UNIX does not offer the necessary time
  3488.    conversion APIs, and (b) FTP protocol offers no mechanism for doing
  3489.    the same thing in the opposite direction.)
  3490.      _________________________________________________________________
  3491.    
  3492.     3.6.3. Recovery
  3493.     
  3494.    Recovery is available for downloads too, but there are some
  3495.    differences from the uploading case described in [290]Section 3.5.3:
  3496.    
  3497.      * The transfer must be in BINARY mode. It can not be in text mode,
  3498.        even if the FTP server is on the same kind of platform as Kermit,
  3499.        and even if there is no character-set translation. The original
  3500.        download must also have been in binary mode.
  3501.      * The FTP server must support the REST ("restart") command.
  3502.        Unfortunately, this is not a standard command; at this writing, it
  3503.        is described only in an Internet Draft, not an RFC or Internet
  3504.        Standard, but nevertheless it is found in several popular FTP
  3505.        servers, such as [291]ProFTPD.
  3506.        
  3507.    Here's how download recovery works:
  3508.    
  3509.      * Kermit checks for conflicting switches, such as /UPDATE, /COMMAND,
  3510.        or /FILTER. If /RECOVER is given with these switches an error
  3511.        occurs.
  3512.      * The prevailing transfer mode (SET FTP TYPE) must be BINARY. If it
  3513.        is not, the /BINARY switch must have been included with the FTP
  3514.        [M]GET command.
  3515.        If the /RECOVER switch is accepted, then for each selected file:
  3516.      * A SIZE command is sent for the file (using its remote name). If
  3517.        the reply indicates the file was not found, or the SIZE command
  3518.        was not understood, or any other kind of error, recovery is
  3519.        canceled (i.e. the entire file is downloaded). Otherwise:
  3520.      * A MDTM (modification time) command is sent for the file. If a
  3521.        valid reply is received, and the modification time of the remote
  3522.        file is later than that of the local file, recovery is canceled.
  3523.        Otherwise:
  3524.      * If the sizes of the two files are identical, the file is not sent.
  3525.        Otherwise:
  3526.      * Kermit sends the REST command to the server, indicating the size
  3527.        of the local file. If the server responds affirmatively, Kermit
  3528.        opens the local file in append mode and appends the incoming data
  3529.        to it. Otherwise, recovery is canceled and the entire file is
  3530.        downloaded.
  3531.        
  3532.    The /RECOVER switch can be included with any FTP GET or MGET command,
  3533.    even if it specifies a group of files. This lets you resume an
  3534.    interrupted batch transfer from where it left off. The files that were
  3535.    already completely sent are skipped, the file that was interrupted is
  3536.    recovered, and the remaining files are uploaded. BUT... unlike with
  3537.    uploading, where this can be done with any mixture of text and binary
  3538.    files, when downloading, it can only be done if all the files are
  3539.    binary.
  3540.    
  3541.    It doesn't matter how the original partial file was downloaded -- FTP,
  3542.    Kermit, Zmodem, etc: as long as the preconditions are met, it can be
  3543.    recovered with FTP [M]GET /RECOVER, or for that matter also with GET
  3544.    /RECOVER (using Kermit protocol).
  3545.    
  3546.    [ [292]Top ] [ [293]Contents ] [ [294]C-Kermit Home ] [ [295]Kermit
  3547.    Home ]
  3548.      _________________________________________________________________
  3549.    
  3550.   3.7. Translating Character Sets
  3551.   
  3552.    A possibly unique feature of Kermit's FTP client is its ability to
  3553.    convert character sets when transferring files in text mode,
  3554.    independent of the capabilites of the FTP server, as well as to
  3555.    translate the character sets of filenames regardless of transfer mode.
  3556.    For compatibility with existing FTP clients, and because there is a
  3557.    certain performance penalty, Kermit won't do this unless you ask for
  3558.    it. If you enable this feature, you need to inform Kermit of the
  3559.    character set (to be) used on the server and in some cases (explained
  3560.    below) also the local file character set. This discussion assumes you
  3561.    know a bit about character sets (as you must if you have to use them);
  3562.    see Chapter 16 of [296]Using C-Kermit for a detailed treatment. The
  3563.    Kermit commands for FTP character-set conversion are:
  3564.    
  3565.    SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
  3566.           Whether to translate character sets when transferring text
  3567.           files with FTP. OFF by default. Set this to ON to enable
  3568.           character-set translation for subsequent FTP uploads and
  3569.           downloads.
  3570.           
  3571.    SET FTP SERVER-CHARACTER-SET [297]name
  3572.           Text character set (to be) used by the server. Most FTP servers
  3573.           are ignorant of character sets, so all translations are done
  3574.           unilaterally by Kermit's FTP client. This means that when
  3575.           downloading files, you must know in advance the character-set
  3576.           used in the files you are downloading (and in their names).
  3577.           When uploading, you must specify the character-set to which
  3578.           local filenames and text-file contents are to be translated for
  3579.           transmission to the server. If you SET FTP
  3580.           CHARACTER-SET-TRANSLATION ON but do not specify an FTP
  3581.           SERVER-CHARACTER-SET, [298]UTF8 is used, since this is the new
  3582.           Internet standard international character set; it is upwards
  3583.           compatible with ASCII and it encompasses most written languages
  3584.           and therefore does not favor any particular group of people, as
  3585.           any other default would do. If you SET FTP SERVER-CHARACTER-SET
  3586.           to something (anything) when FTP CHARACTER-SET TRANSLATION is
  3587.           OFF, this also sets the latter ON.
  3588.           
  3589.    SET FILE CHARACTER-SET [299]name
  3590.           This is the regular Kermit (non-FTP-specific) command for
  3591.           identifying the character set (to be) used in local text files
  3592.           and filenames.
  3593.           
  3594.    TO REITERATE: If you SET FTP CHARACTER-SET TRANSLATION ON but do not
  3595.    specify an FTP SERVER-CHARACTER-SET, outbound text files are converted
  3596.    to UTF-8 and inbound text files are assumed to be UTF-8. If this is
  3597.    not appropriate, be sure to also specify the desired FTP
  3598.    SERVER-CHARACTER-SET.
  3599.    
  3600.    You can use "special" (non-ASCII) characters in filenames in all the
  3601.    client / server file management commands (FTP MKDIR, RMDIR, DIRECTORY,
  3602.    VDIRECTORY, DELETE, etc), and also in file-transfer commands. When
  3603.    giving commands such as FTP DIR (RDIR) and FTP PWD (RPWD), the reply
  3604.    is translated too, so you can read it. In this example, the client and
  3605.    server use entirely different codes to represent the special
  3606.    characters of German:
  3607.    
  3608.   C-Kermit> ftp xyzcorp.de /anonymous
  3609.   C-Kermit> set ftp server-character-set latin1
  3610.   C-Kermit> set file character-set german
  3611.   C-Kermit> rcd StΣdte
  3612.   C-Kermit> rpwd
  3613.   "/pub/ftp/StΣdte is current directory"
  3614.   C-Kermit> rdir
  3615.   -rw-rw----  1 olaf     54018 Jan  6 17:58 Adenbⁿttel.txt
  3616.   -rw-rw----  1 ursula     373 Jan  5 15:19 A▀lar.txt
  3617.   -rw-rw----  1 gisbert    482 Jan  5 15:20 Blowatz.txt
  3618.   -rw-rw----  1 gudrun     124 Jan  5 15:19 B÷blingen.txt
  3619.   -rw-rw----  1 olga     14348 Jan  7 14:23 K÷ln.txt
  3620.  
  3621.    When the client and server file systems use different character sets,
  3622.    you should take care to use only those characters that the two sets
  3623.    share in common when creating filenames or text-file contents. For
  3624.    example, PC code pages contain a lot line- and box-drawing characters,
  3625.    and sometimes "smart quotes", etc, that are not found in ISO standard
  3626.    8-bit character sets. You should be especially careful to avoid using
  3627.    such characters in filenames.
  3628.    
  3629.    [ [300]C-Kermit Character Sets ]
  3630.      _________________________________________________________________
  3631.    
  3632.     3.7.1. Character Sets and Uploading
  3633.     
  3634.    Kermit's PUT and MPUT commands include full file-scanning
  3635.    capabilities, as described in [301]Section 4. Thus if FTP
  3636.    CHARACTER-SET-TRANSLATION is ON and your character-set associations
  3637.    are set up appropriately, Kermit automatically switches on a per-file
  3638.    basis between text and binary mode, and for each text file between
  3639.    your chosen 7-bit text character set (e.g. ASCII or ISO 646 German),
  3640.    8-bit text (e.g. Latin-1 or Japanese EUC), UCS-2, and UTF-8, and
  3641.    converts each of these automatically to the server character-set, and
  3642.    furthermore automatically differentiates between the Little and Big
  3643.    Endian forms of UCS-2, always sending in Big Endian form.
  3644.    
  3645.      WARNING: It is not advisable to use UCS-2 (or any Unicode
  3646.      transformation other than UTF-8) "on the wire", i.e. as a server
  3647.      character set. Most FTP servers are not able to cope with it, since
  3648.      it contains lots of 0 (NUL) characters. If you do use it, Kermit
  3649.      does not translate filenames to or from UCS-2, for reasons well
  3650.      known to C programmers (for example, UNIX APIs assume filename
  3651.      strings are NUL-terminated). [302]UTF-8 is the preferred (and
  3652.      standard) Unicode format for the Internet.
  3653.      
  3654.    FTP character-set translations differ from the regular Kermit ones by
  3655.    not restricting translations to a file-character-set /
  3656.    transfer-character-set pair. You can have Kermit's FTP client
  3657.    translate between any pair of character sets it knows about. You can
  3658.    see the list of supported character sets by typing either of the
  3659.    following:
  3660.    
  3661.   set ftp server-character-set ?
  3662.   set file character-set ?
  3663.  
  3664.    A typical list looks like this ([303]CLICK HERE for an explanation of
  3665.    the names):
  3666.    
  3667.   C-Kermit>set file char ? One of the following:
  3668.    ascii            cp869-greek       hebrew-7         mazovia-pc
  3669.    british          cyrillic-iso      hebrew-iso       next-multinational
  3670.    bulgaria-pc      danish            hp-roman8        norwegian
  3671.    canadian-french  dec-kanji         hungarian        portuguese
  3672.    cp1250           dec-multinational iso2022jp-kanji  shift-jis-kanji
  3673.    cp1251-cyrillic  dg-international  italian          short-koi
  3674.    cp1252           dutch             jis7-kanji       spanish
  3675.    cp437            elot927-greek     koi8             swedish
  3676.    cp850            elot928-greek     koi8r            swiss
  3677.    cp852            euc-jp            koi8u            ucs2
  3678.    cp855-cyrillic   finnish           latin1-iso       utf8
  3679.    cp858            french            latin2-iso
  3680.    cp862-hebrew     german            latin9-iso
  3681.    cp866-cyrillic   greek-iso         macintosh-latin
  3682.   C-Kermit>
  3683.  
  3684.    Thus you can translate not only between private sets (like PC code
  3685.    pages) and standard ones (like Latin-1) as in Kermit protocol, but
  3686.    also between any given pair of private sets (e.g. CP852 and Mazovia).
  3687.    All conversions go through Unicode as the intermediate character set,
  3688.    resulting in a minimum of character loss, since Unicode is a superset
  3689.    of all other character sets known to Kermit.
  3690.    
  3691.    In addition to the SET commands listed above, the FTP PUT and MPUT
  3692.    commands include switches that apply only to the current command:
  3693.    
  3694.    /LOCAL-CHARACTER-SET:name
  3695.           
  3696.    /SERVER-CHARACTER-SET:name
  3697.           Use these switches to force a particular translation. These
  3698.           switches override the global FTP CHARACTER-SET-TRANSLATION and
  3699.           SERVER-CHARACTER-SET settings and also character-set
  3700.           differentiation by file scanning for the duration of the PUT or
  3701.           MPUT command. The file scan is still performed, however, to
  3702.           determine whether the file is text or binary; thus these
  3703.           switches do not affect binary files unless you also include the
  3704.           /TEXT switch to force all files to be treated as text.
  3705.           
  3706.    In other words, if you include one or both of these switches with a
  3707.    PUT or MPUT command, they are used. Similarly, the /TRANSPARENT switch
  3708.    disables character-set translation for the PUT or MPUT command despite
  3709.    the prevailing FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET
  3710.    settings.
  3711.    
  3712.    When uploading, the FILE CHARACTER-SET setting is ignored unless you
  3713.    have forced Kermit not to [304]scan local files by including a /TEXT
  3714.    or /BINARY switch with your [M]PUT command, or by disabling automatic
  3715.    text/binary switching in some other way.
  3716.    
  3717.    Examples:
  3718.    
  3719.     1. Suppose you have a CP852 (East European) text file that you want
  3720.        to upload and store in ISO Latin Alphabet 2 encoding:
  3721.  
  3722.   ftp put /local-char:cp852 /server-char:latin2 magyar.txt
  3723.     2. Suppose you always want your text files converted to Latin-2 when
  3724.        uploading with FTP. Then put:
  3725.  
  3726.   set ftp server-character-set latin2
  3727.        in your Kermit customization file, and then you can omit the
  3728.        /SERVER-CHARACTER-SET: switch from your FTP PUT commands:
  3729.  
  3730.   ftp put /local-char:cp852 magyar.txt
  3731.     3. Now suppose that all the text files on your PC are written in
  3732.        Hungarian, but they have a variety of encodings, and you don't
  3733.        want to have to include the /LOCAL-CHARACTER-SET: switch on every
  3734.        FTP PUT command, or (more to the point) you want to be able to
  3735.        send a mixture of these files all at once. Put these commands in
  3736.        your Kermit customization file:
  3737.  
  3738.   set ftp server-character-set latin2            ; ISO 8859-2
  3739.   set file default 7-bit-character-set hungarian ; ISO 646 Hungarian
  3740.   set file default 8-bit-character-set cp852     ; PC East European Code Page
  3741.        and now PUT and MPUT will automatically detect and switch among
  3742.        ISO 646 Hungarian, Code Page 852, UTF-8, and UCS-2 encodings,
  3743.        translating each one to Latin-2 for uploading:
  3744.  
  3745.   ftp put *.txt
  3746.  
  3747.    And since binary files are also detected automatically, the latter can
  3748.    be simplified to:
  3749.    
  3750.   ftp put *
  3751.  
  3752.    even when "*" matches a diverse collection of binary and text files,
  3753.    because translations are skipped automatically for binary files.
  3754.      _________________________________________________________________
  3755.    
  3756.     3.7.2. Character Sets and Downloading
  3757.     
  3758.    The commands and switches are the same as for uploading, but automatic
  3759.    character-set switching works differently, since Kermit can't scan the
  3760.    server files in advance. Instead, the transfer mode (text or binary)
  3761.    is based on the filenames; each name is compared with Kermit's list of
  3762.    text name patterns and binary name patterns. If the name matches a
  3763.    binary pattern (for example, if the filename is oofa.tar.gz and one of
  3764.    the filename patterns is "*.gz"), the file is downloaded in binary
  3765.    mode; otherwise if it matches a text pattern (e.g. oofa.txt matches
  3766.    "*.txt"), it is transferred in text ("ascii") mode. Otherwise, it is
  3767.    transferred in the prevailing FTP TYPE.
  3768.    
  3769.    In C-Kermit 8.0, the pattern lists used with FTP GET are not the same
  3770.    lists used with Kermit transfers, and can not be viewed with SHOW
  3771.    PATTERNS, nor adjusted with ADD and REMOVE TEXT-PATTERNS and
  3772.    BINARY-PATTERNS, or SET FILE TEXT-PATTERNS and BINARY-PATTERNS.
  3773.    Configuration of the FTP patterns list will be added in a future
  3774.    release.
  3775.    
  3776.    Examples:
  3777.    
  3778.    get /server-char:latin1 /local-char:cp850 Grⁿ▀e.txt
  3779.           In this command, the filename contains special characters,
  3780.           which you enter using whatever character set your local
  3781.           computer uses, in this case PC Code Page 850 (cp850). The
  3782.           command tells Kermit (in case it didn't know already from its
  3783.           FILE CHARACTER-SET setting) that the local character set is
  3784.           cp850 and the server's character-set is ISO 8859-1 Latin
  3785.           Alphabet 1 (latin1). Kermit translates the filename from cp850
  3786.           to latin1 and sends the latin1 name to the server. Since it's a
  3787.           text file (matches "*.txt"), its contents are translated to
  3788.           cp850 on arrival, and it is saved with a cp850 name.
  3789.           
  3790.    mget /text /server:latin1 /local:utf8 *.txt
  3791.           This command:
  3792.           
  3793.           + Tells C-Kermit that the server's files are encoded in ISO
  3794.             8859-1 Latin Alphabet 1.
  3795.           + Tells C-Kermit to translate the incoming files into Unicode
  3796.             UTF-8 for storage.
  3797.           + Asks the server to send all ".txt" files in text mode.
  3798.             
  3799.    mget /server:latin1 /local:utf8 *
  3800.           Tells Kermit to get all files from the server's directory,
  3801.           switching between text and binary mode based on the filename.
  3802.           The names of all the files are translated (to UTF-8 in this
  3803.           case), but contents are translated (also to UTF-8) only for
  3804.           text files.
  3805.           
  3806.    Note that any pair of 8-bit character sets is likely to have some
  3807.    incompatibilities. Any characters in the source file that do not have
  3808.    equivalents in the destination file's character set are converted to
  3809.    question marks. This applies to both filenames and to text file
  3810.    contents.
  3811.    
  3812.    Also note that the server's ability to accept special characters in
  3813.    filenames depends on the particular server. For example:
  3814.    
  3815.   get Grⁿ▀e.txt
  3816.  
  3817.    works with WU-FTPD, but:
  3818.    
  3819.   mget Grⁿ▀*.txt
  3820.  
  3821.    does not.
  3822.      _________________________________________________________________
  3823.    
  3824.     3.7.3. RFC2640
  3825.     
  3826.    [305]RFC2640, July 1999, specifies a method by which the FTP client
  3827.    and server can negotiate the use of UTF8. However, RFC2640-capable
  3828.    servers are rare to nonexistent at this writing, and in any case you
  3829.    don't need them to be able to transfer text in UTF8. C-Kermit lets you
  3830.    upload and download text files in any character set it knows about,
  3831.    converting to or from any other character set it knows about, without
  3832.    the knowledge, permission, or cooperation of the server, and
  3833.    regardless of its capabilities.
  3834.    
  3835.    [ [306]Top ] [ [307]Contents ] [ [308]C-Kermit Home ] [ [309]Kermit
  3836.    Home ]
  3837.      _________________________________________________________________
  3838.    
  3839.   3.8. FTP Command Shortcuts
  3840.   
  3841.    C-Kermit's FTP client coexists with other C-Kermit functions by
  3842.    requiring the "ftp" prefix for each FTP-related command: FTP OPEN, FTP
  3843.    GET, FTP BYE, and so on. For interactive use, however, this can be
  3844.    rather awkward and sometimes surprising, for example when a GET
  3845.    command starts a Kermit GET rather than an FTP GET. In fact, many
  3846.    Kermit commands might just as easily apply to an FTP connection: GET,
  3847.    PUT (SEND), BYE, and CLOSE. The following command lets you choose how
  3848.    these commands are interpreted:
  3849.    
  3850.    SET GET-PUT-REMOTE { AUTO, KERMIT, FTP }
  3851.           Controls the orientation of GET, PUT, REMOTE and other
  3852.           file-transfer and client/server commands that might apply to
  3853.           either Kermit or FTP. The default setting is AUTO, meaning that
  3854.           these commands apply to FTP if an FTP connection is open, and
  3855.           to Kermit otherwise. KERMIT means they always apply to Kermit,
  3856.           FTP means they always apply to FTP.
  3857.           
  3858.    Here is a complete list of affected commands:
  3859.    
  3860.  Kermit Command               FTP Equivalent
  3861.   (none)                       FTP [ OPEN ]
  3862.   LOGIN                        FTP USER
  3863.   LOGOUT                       FTP RESET
  3864.   BYE                          FTP BYE
  3865.   FINISH                       FTP BYE
  3866.   CLOSE                        FTP BYE
  3867.   HANGUP                       FTP BYE
  3868.   BINARY                       FTP TYPE BINARY
  3869.   TEXT (or ASCII)              FTP TYPE ASCII
  3870.   SEND (or PUT)                FTP PUT
  3871.   MSEND (or MPUT)              FTP MPUT
  3872.   RESEND                       FTP PUT /RECOVER
  3873.   CSEND                        FTP PUT /COMMAND
  3874.   GET                          FTP GET
  3875.   MGET                         FTP MGET
  3876.   REGET                        FTP GET /RECOVER
  3877.   REMOTE HELP      (RHELP)     FTP HELP
  3878.   REMOTE CD        (RCD)       FTP CD (CWD)
  3879.   REMOTE PWD       (RPWD)      FTP PWD
  3880.   REMOTE DIRECTORY (RDIR)      FTP DIRECTORY
  3881.   REMOTE DELETE    (RDEL)      FTP DELETE
  3882.   REMOTE MKDIR     (RMKDIR)    FTP MKDIR
  3883.   REMOTE RMDIR     (RRMDIR)    FTP RMDIR
  3884.   REMOTE RENAME    (RRENAME)   FTP RENAME
  3885.   REMOTE TYPE      (RTYPE)     FTP TYPE
  3886.   REMOTE EXIT      (REXIT)     FTP BYE
  3887.  
  3888.    The commands in the right-hand column always access FTP. The commands
  3889.    in the left column can access either Kermit protocol or FTP:
  3890.    
  3891.      * When GET-PUT-REMOTE is set to KERMIT, or to AUTO when there is no
  3892.        FTP connection, the commands in the left-hand column access Kermit
  3893.        protocol, and those right-hand column are required for FTP.
  3894.      * When GET-PUT-REMOTE is set to FTP, or to AUTO when there is an
  3895.        active FTP connection, the commands in the left-hand column access
  3896.        the FTP connection and can not be used to access Kermit protocol.
  3897.        In this case, if you want to be able to use both Kermit protocol
  3898.        and the FTP connection, you must SET GET-PUT-REMOTE KERMIT, and
  3899.        then use the FTP commands in the right-hand column to access the
  3900.        FTP connection.
  3901.        
  3902.    Note that file-management commands such as DIRECTORY, DELETE, CD, PWD,
  3903.    MKDIR, RMDIR, HELP, RENAME, COPY, TYPE, and so on, always apply
  3904.    locally, no matter what kind of connection you have. This is the
  3905.    opposite of most FTP clients, where these commands are intended for
  3906.    the server, and require an "L" prefix for local execution (e.g. "dir"
  3907.    gets a directory listing from the server, "ldir" gets a local
  3908.    directory listing). To illustrate with the CD command and a typical
  3909.    UNIX FTP client:
  3910.    
  3911.  Client   Server      Change Local Directory     Change Remote Directory
  3912.   FTP      FTP         lcd                        cd (cwd)
  3913.   Kermit   Kermit      cd                         rcd, remote cd
  3914.   Kermit   FTP         cd                         ftp cd, rcd, remote cd
  3915.  
  3916.    Also note that not all REMOTE commands are useful with FTP, since FTP
  3917.    servers do not offer the corresponding functions. These include:
  3918.    
  3919.      * REMOTE ASSIGN  - FTP servers don't have variables
  3920.      * REMOTE COPY    - FTP servers don't copy files
  3921.      * REMOTE HOST    - FTP servers don't execute host (shell) commands
  3922.      * REMOTE KERMIT  - FTP servers don't execute Kermit commands
  3923.      * REMOTE PRINT   - FTP servers don't print files
  3924.      * REMOTE QUERY   - FTP servers don't have variables
  3925.      * REMOTE SET     - FTP servers don't have Kermit settings
  3926.      * REMOTE WHO     - FTP servers don't send user lists
  3927.        
  3928.    Finally note that command shortcuts do not apply to the HELP command.
  3929.    For help about an FTP command, use (for example) "help ftp delete",
  3930.    not "help delete" or "help rdelete".
  3931.    
  3932.    [ [310]Top ] [ [311]Contents ] [ [312]C-Kermit Home ] [ [313]Kermit
  3933.    Home ]
  3934.      _________________________________________________________________
  3935.    
  3936.   3.9. Dual Sessions
  3937.   
  3938.    You can have an FTP session open at the same time as a regular Kermit
  3939.    SET LINE or SET HOST (terminal) session. In this case, the default SET
  3940.    GET-PUT-REMOTE AUTO setting should ensure that all "two-faced"
  3941.    commands like GET, PUT, REMOTE, HANGUP, BYE, etc, apply to the Kermit
  3942.    session, and all commands for the FTP session must include the FTP
  3943.    prefix. To be absolutely certain, you can use SET GET-PUT-REMOTE
  3944.    KERMIT.
  3945.    
  3946.   ftp foo.bar.baz.com
  3947.   if fail ...
  3948.   (log in)
  3949.   set host foo.bar.baz.com
  3950.   if fail ...
  3951.   (log in)
  3952.  
  3953.    Now you have both an FTP and Telnet connection to the same host (of
  3954.    course they could also be to different hosts, and you could also have
  3955.    a direct or dialed serial connection instead of a Telnet connection).
  3956.    Now assuming you have a Kermit server on the far end of the Kermit
  3957.    connection:
  3958.    
  3959.   rcd incoming      ; Changes Kermit server's directory (= REMOTE CD)
  3960.   ftp cd incoming   ; Changes FTP server's directory
  3961.   put oofa.txt      ; Sends a file on the Kermit connection
  3962.   ftp put oofa.txt  ; Sends a file on the FTP connection
  3963.   bye               ; Shuts down the Kermit connection
  3964.   ftp bye           ; Shuts down the FTP connection
  3965.  
  3966.    Note that PUT and SEND are synonyms for both FTP and Kermit
  3967.    connections.
  3968.    
  3969.    You can also establish dual sessions on the Kermit command line:
  3970.    
  3971.   kermit -j host1 -9 host2
  3972.  
  3973.    This makes a Telnet connection to host1 and an FTP connection to
  3974.    host2.
  3975.    
  3976.    [ [314]Top ] [ [315]Contents ] [ [316]C-Kermit Home ] [ [317]Kermit
  3977.    Home ]
  3978.      _________________________________________________________________
  3979.    
  3980.   3.10. Automating FTP Sessions
  3981.   
  3982.    Most of Kermit's scripting features can be used to make and control
  3983.    FTP sessions: FOR and WHILE loops, IF-ELSE and SWITCH constructions,
  3984.    variables, arrays, built-in functions, and all the rest. You can't use
  3985.    INPUT, MINPUT, OUTPUT, CLEAR, or SCRIPT on an FTP session, but these
  3986.    are not needed since the FTP protocol is well defined.
  3987.    
  3988.    [318]CLICK HERE for an FTP scripting tutorial.
  3989.    
  3990.     3.10.1. FTP-Specific Variables and Functions
  3991.     
  3992.    The following variable tells whether an FTP connection is open:
  3993.    
  3994.    \v(ftp_connected)
  3995.           1 if there is an active FTP connection, 0 if there isn't.
  3996.           
  3997.    The FTP OPEN command sets:
  3998.    
  3999.    \v(ftp_host)
  4000.           The host to which the most recent FTP connection was made.
  4001.           
  4002.    \v(ftp_security)
  4003.           The security method negotiated for the current FTP session. The
  4004.           value is "NULL" when no security is used. See [319]3.2. Making
  4005.           Secure FTP Connections.
  4006.           
  4007.    \v(ftp_server)
  4008.           The OS type (UNIX, VMS, etc) of the FTP server host.
  4009.           
  4010.    The FTP USER command (or FTP OPEN /USER:, or FTP with automatic login)
  4011.    sets:
  4012.    
  4013.    \v(ftp_loggedin)
  4014.           1 if you are logged in to an FTP server, 0 if you are not.
  4015.           
  4016.    The current COMMAND-PROTECTION-LEVEL and DATA-PROTECTION-LEVEL values
  4017.    are reflected in:
  4018.    
  4019.    \v(ftp_cpl)
  4020.           
  4021.    \v(ftp_dpl)
  4022.           The values are "clear", "confidential", "safe" or "private".
  4023.           See [320]3.2. Making Secure FTP Connections.
  4024.           
  4025.    The FTP GET-PUT-REMOTE setting is reflected in:
  4026.    
  4027.    \v(ftp_getputremote)
  4028.           The values are "auto", "ftp", or "kermit".
  4029.           
  4030.    Every FTP command sets the \v(success) variable, as well as the
  4031.    following two FTP-specific variables:
  4032.    
  4033.    \v(ftp_code)
  4034.           The standardized numeric FTP protocol code from the server's
  4035.           response to the last client command, a 3-digit decimal number
  4036.           defined in [321]RFC959. Briefly:
  4037.           
  4038.           1xx = Positive Preliminary Reply
  4039.           2xx = Positive Completion Reply
  4040.           3xx = Positive Intermediate Reply
  4041.           4xx = Transient Negative Completion Reply
  4042.           5xx = Permanent Negative Completion Reply
  4043.           
  4044.    \v(ftp_message)
  4045.           The text message, if any, from the server's response to the
  4046.           last client command. If the most recent response had multiple
  4047.           lines, this variable has only the final line. These messages
  4048.           are not standardized and vary in format and content from server
  4049.           to server. Synonym: \v(ftp_msg).
  4050.           
  4051.    FTP file transfers set the regular Kermit transfer status variables:
  4052.    
  4053.   \v(cps)         Characters per second of most recent transfer.
  4054.   \v(filespec)    File specification used in most recent transfer.
  4055.   \v(fsize)       Size of file most recently transferred.
  4056.   \v(tfsize)      Total size of file group most recently transferred.
  4057.   \v(xferstatus)  Status of most recent transfer (0 = success, 1 = failure).
  4058.   \v(tftime)      Elapsed time of most recent transfer, in seconds.
  4059.  
  4060.    During an FTP transfer, the per-file variables are:
  4061.    
  4062.   \v(filename)    Name of current file.
  4063.   \v(filenumber)  Ordinal file number in group (1, 2, 3, ...)
  4064.      _________________________________________________________________
  4065.    
  4066.     3.10.2. Examples
  4067.     
  4068.    Let's begin with a simple example showing how to log in, send some
  4069.    files, and log out:
  4070.    
  4071.   define error if fail { ftp bye, stop 1 Error: \%1 }
  4072.   set transact brief
  4073.   log t
  4074.   ftp ftp.xyzcorp.com /anonymous
  4075.   if fail stop 1 Connection failed
  4076.   if not \v(ftp_loggedin) stop 1 Login failed
  4077.   ftp cd incoming
  4078.   error {ftp cd}
  4079.   cd upload
  4080.   error {local cd}
  4081.   ftp put /delete *
  4082.   error {put}
  4083.   ftp bye
  4084.  
  4085.    First we define an error handling macro to be used after the
  4086.    connection is made. Then we set up a brief-format transaction log to
  4087.    keep a record of our file transfers. Then we make a connection to the
  4088.    host and log in anonymously. The "if fail" command checks whether the
  4089.    connection was made. The "if not" command checks whether login was
  4090.    successful. Obviously the script should not continue unless both tests
  4091.    succeed.
  4092.    
  4093.    Next we change to the server's 'incoming' directory and to our own
  4094.    'upload' directory, and send all the files that are in it (they can be
  4095.    any mixture of text and binary files), deleting each source file
  4096.    automatically after it is successfully uploaded. Each of these
  4097.    operations is checked with the ERROR macro, which prevents the script
  4098.    from continuing past a failure.
  4099.    
  4100.    Finally we close the FTP session with the "bye" command.
  4101.    
  4102.    Just like any other Kermit script, this one can be used in many ways:
  4103.    
  4104.      * It can be stored in a file, and Kermit can be told to TAKE the
  4105.        file.
  4106.      * In UNIX, it can be a "[322]kerbang" script and therefore run
  4107.        directly from the shell prompt or as a cron job.
  4108.        
  4109.    We could have used command shortcuts like "rcd", "put", and "bye", but
  4110.    since they can be ambiguous under certain circumstances, it is better
  4111.    to avoid them in scripts; they are intended mainly for convenience
  4112.    during interactive use. However, if you wish to use the shortcuts in a
  4113.    script, you can do it this way (error handling omitted for brevity):
  4114.    
  4115.   local \%t                       ; Declare a local temporary veriable
  4116.   assign \%t \v(ftp_getputremote) ; Save current FTP GET-PUT-REMOTE setting
  4117.   set ftp get-put-remote ftp      ; Choose FTP orientation
  4118.   ftp xyzcorp.com /anonymous      ; Open an FTP connection
  4119.   get oofa.txt                    ; GET a file
  4120.   put foo.bar                     ; PUT a file
  4121.   rdel yesterday.log              ; Delete a file on the server
  4122.   bye                             ; Log out and disconnect from server.
  4123.   set ftp get-put-remote \%t      ; Restore previous GET-PUT-REMOTE setting
  4124.  
  4125.    Of course, FTP scripts can also be written as macros. This lets you
  4126.    pass parameters such as hostnames, usernames, and filenames to them:
  4127.    
  4128.   define doftpget {
  4129.       if < \v(argc) 4 end 1 Usage: \%0 host user remotefile [ localfile ]
  4130.       ftp \%1 /user:\%2
  4131.       if fail end 1 FTP OPEN \%1 failed
  4132.       if not \v(ftp_loggedin) end 1 FTP LOGIN failed
  4133.       ftp get {\%3} {\%4}
  4134.       if fail end 1 FTP GET \%3 failed
  4135.       ftp bye
  4136.   }
  4137.  
  4138.    Add this definition to your Kermit customization file, and it will
  4139.    always be available when you start Kermit. This macro lets you
  4140.    download a file with FTP by giving a single command, e.g.:
  4141.    
  4142.   doftpget xyzcorp.com anonymous oofa.txt
  4143.  
  4144.    [323]CLICK HERE to visit the Kermit FTP script-writing tutorial.
  4145.    
  4146.    [ [324]Top ] [ [325]Contents ] [ [326]C-Kermit Home ] [ [327]Kermit
  4147.    Home ]
  4148.      _________________________________________________________________
  4149.    
  4150.   3.11. Advanced FTP Protocol Features
  4151.   
  4152.    FEAT and NLST are not supported by C-Kermit since they are not yet
  4153.    standardized, nor can they be found in most FTP servers at this
  4154.    writing. Similarly for the various mail-sending options.
  4155.    
  4156.    [ [328]Top ] [ [329]Contents ] [ [330]C-Kermit Home ] [ [331]Kermit
  4157.    Home ]
  4158.   __________________________________________________________________________
  4159.  
  4160. 4. FILE SCANNING
  4161.  
  4162.    A new feature called file scanning is used in various contexts to
  4163.    determine if a file is text or binary, and if it is text, what kind of
  4164.    text. The overhead of file scanning is surprisingly tolerable, usually
  4165.    about a quarter second per file. File scanning is now used instead of
  4166.    filename patterns unless you SET FILE SCAN OFF, which restores the
  4167.    previous behavior.
  4168.    
  4169.    The primary benefit of file scanning is in file transfer. For all
  4170.    practical purposes, now you can stop worrying about whether a file
  4171.    should be sent in binary or text mode, or about sending mixtures of
  4172.    text and binary files in a single operation, or configuring and
  4173.    fine-tuning your lists of binary-file and text-file name patterns: now
  4174.    it all just works.
  4175.    
  4176.    File scanning is done by the file sender, which determines the type of
  4177.    each file before it sends it and informs the receiver (Kermit or FTP
  4178.    server) of the type. File scanning is NOT done by the receiver,
  4179.    because it is the sender's responsibility to determine each file's
  4180.    type, send the file in the right mode, and inform the receiver of the
  4181.    mode. If both transfer partners are capable of this (or any other)
  4182.    form of automatic text/binary mode switching, then files can be sent
  4183.    in both directions with no worries about corruption due to
  4184.    inappropriate transfer mode. (As noted in [332]Section 3, FTP servers
  4185.    don't do this, so this discussion does not apply when using Kermit to
  4186.    download from an FTP server.)
  4187.    
  4188.    The rest of this section is mainly for the curious. If you don't read
  4189.    it and simply accept all defaults, every file you send should go in
  4190.    the appropriate mode automatically. As always, however, for
  4191.    character-set translation to work for 7- and 8-bit character-set
  4192.    files, the appropriate SET FILE CHARACTER-SET command(s) must have
  4193.    been executed to identify their encoding (Kermit's default file
  4194.    character-set is neutral ASCII except on platforms like HP-UX or
  4195.    DG/UX, where the default file character-set is known). And of course,
  4196.    receiving is another matter -- obviously the other Kermit must also
  4197.    send each file in the appropriate mode.
  4198.    
  4199.    Scanning is more reliable than filename patterns simply because
  4200.    filenames are not reliable indicators of the file's contents. Classic
  4201.    examples include ".doc" files, which are binary if Microsoft Word
  4202.    documents but text on most other platforms, and ".com" files, which
  4203.    are binary on DOS and Windows but text on VMS. Anyway, nobody knows
  4204.    the naming conventions (if any) of all the applications (and persons!)
  4205.    on your computer. Scanning, on the other hand, determines each file's
  4206.    type by inspecting its contents rather than just looking at its name.
  4207.    
  4208.    Also, file patterns -- even when they work as intended -- categorize
  4209.    each file only as text or binary, whereas file scanning can make finer
  4210.    distinctions:
  4211.    
  4212.    BINARY
  4213.           Binary data, not to be converted in any way. Examples include
  4214.           binary machine code (executable programs), graphics images
  4215.           (GIF, JPG, etc), compressed files (Z, GZ, etc), archives and
  4216.           packages (ZIP, TAR, RPM, etc), object files and libraries (OBJ,
  4217.           DLL, etc).
  4218.           
  4219.    7-BIT TEXT
  4220.           Text encoded in a 7-bit character set such as ASCII or one of
  4221.           the ISO 646 national versions. Kermit has no way to tell which
  4222.           character is used, only that it's 7-bit text. Typical examples
  4223.           include program source code, README files, Perl or Kermit
  4224.           scripts, plain-text email, HTML, TeX, and various textual
  4225.           encodings of binary files: Hex, Base64, etc. When sending such
  4226.           files, the FILE DEFAULT 7BIT-CHARACTER-SET is used as the file
  4227.           character-set, and then the appropriate transfer character set
  4228.           is chosen from the associations list (ASSOCIATE, SHOW
  4229.           ASSOCIATIONS).
  4230.           
  4231.    8-BIT TEXT
  4232.           Text encoded in an 8-bit character set such as Latin-1,
  4233.           Latin-2, Latin/Hebrew, Latin/Cyrillic, KOI8, HP-Roman8, JIS X
  4234.           0208, Code Page 437, or Code Page 1252. Again, Kermit has no
  4235.           way of knowing which particular set is in use, only that it's
  4236.           8-bit text. When sending such files, the FILE DEFAULT
  4237.           8BIT-CHARACTER-SET is used as the file character-set, and then
  4238.           the appropriate transfer character set is chosen from the
  4239.           associations list.
  4240.           
  4241.    UCS2 TEXT
  4242.           Unicode in its basic form, 16 bits (2 octets) per character.
  4243.           When sending such files, UCS2 is the file character-set and the
  4244.           byte order is identified automatically; the appropriate
  4245.           transfer character set is chosen from the associations list.
  4246.           Normally this would be UTF8. UTF-16 is not supported yet;
  4247.           Kermit's Unicode translations are restricted to Plane 0, the
  4248.           Base Multilingual Plane (BMP).
  4249.           
  4250.    UTF8 TEXT
  4251.           Unicode in its 8-bit transformation format. When sending such
  4252.           files, UTF8 is the file character-set; the appropriate transfer
  4253.           character set is chosen from the associations list, normally
  4254.           UCS2 or UTF8.
  4255.           
  4256.    File scanning is available in UNIX C-Kermit, in K-95, and to a limited
  4257.    extent, in VMS C-Kermit (full scanning is problematic in VMS because
  4258.    even plain-text files might contain binary record-format information).
  4259.    The relevant commands are:
  4260.    
  4261.    SET TRANSFER MODE { AUTOMATIC, MANUAL }
  4262.           Tells whether the file-transfer mode (text or binary) should be
  4263.           set by automatic or "manual" means. AUTOMATIC is the default,
  4264.           which allows any of the automatic methods that are enabled to
  4265.           do their jobs: FILE SCAN, FILE PATTERNS, peer recognition, etc.
  4266.           MANUAL lets you control the transfer mode with the SET FILE
  4267.           TYPE commands. As always, /TEXT and /BINARY switches on your
  4268.           file-transfer commands override all other methods; if you give
  4269.           one of these switches, scanning is not done. SHOW TRANSFER
  4270.           displays the current TRANSFER MODE setting.
  4271.           
  4272.    SET FILE SCAN { ON [ number ], OFF }
  4273.           Turns this feature on and off. It's ON by default. When OFF,
  4274.           the previous rules apply (SET FILE PATTERNS, etc). When ON is
  4275.           given, you can also specify a number of bytes to be scanned.
  4276.           The default is 49152 (= 48K). If a negative number is given,
  4277.           the entire file is scanned, no matter how big, for maximum
  4278.           certainty (for example, a PostScript file that appears to be
  4279.           plain text might include an embedded graphic past the normal
  4280.           scanning limit). SHOW FILE displays the current FILE SCAN
  4281.           setting.
  4282.           
  4283.    SET FILE DEFAULT 7BIT-CHARACTER-SET name
  4284.           Tells the 7-bit character-set to use if scanning identifies a
  4285.           7-bit text file, e.g. GERMAN. SHOW FILE displays the current
  4286.           SET FILE DEFAULT settings. So does SHOW CHARACTER-SETS.
  4287.           
  4288.    SET FILE DEFAULT 8BIT-CHARACTER-SET name
  4289.           Tells the 8-bit character-set to use if scanning identifies an
  4290.           8-bit text file, e.g. LATIN1. SHOW FILE and SHOW CHARACTER-SET
  4291.           display this.
  4292.           
  4293.    ASSOCIATE FILE-CHARACTER-SET fcs tcs
  4294.           When sending files and a file character-set (fcs) is identified
  4295.           by scanning, this tells C-Kermit which transfer character-set
  4296.           (tcs) to translate it to. It also allows C-Kermit to set the
  4297.           appropriate transfer character-set automatically whenever you
  4298.           give a SET FILE CHARACTER-SET command.
  4299.           
  4300.    ASSOCIATE TRANSFER-CHARACTER-SET tcs fcs
  4301.           When receivinging files and a file arrives whose transfer
  4302.           character-set (tcs) is announced by the sender, this command
  4303.           tells C-Kermit which file character-set (fcs) to translate it
  4304.           to. It also allows C-Kermit to set the appropriate file
  4305.           character-set whenever you give a SET TRANSFER CHARACTER-SET
  4306.           command.
  4307.           
  4308.    SET FILE CHARACTER-SET name
  4309.           When given for a 7-bit set, also sets FILE DEFAULT
  4310.           7BIT-CHARACTER-SET to the same set. When given for an 8-bit
  4311.           set, also sets FILE DEFAULT 8BIT-CHARACTER-SET to the same set.
  4312.           If an ASSOCIATE FILE-CHARACTER-SET command has been given for
  4313.           this set, also sets the corresponding transfer character-set.
  4314.           
  4315.    DIRECTORY /XFERMODE [ filespec ]
  4316.           Performs a file scan of the given files, listing the result for
  4317.           each file. If FILE SCAN is OFF but PATTERNS are ON, the result
  4318.           shown according to the current FILE TEXT-PATTERNS and
  4319.           BINARY-PATTERNS, and are restricted to (B) and (T). When FILE
  4320.           SCAN is ON, the results are:
  4321.           
  4322.   (B)          Binary
  4323.   (T)(7BIT)    Text: 7-bit
  4324.   (T)(8BIT)    Text: 8-bit
  4325.   (T)(UTF8)    Text: Unicode UTF8
  4326.   (T)(UCS2BE)  Text: Unicode UCS2 Big Endian
  4327.   (T)(UCS2LE)  Text: Unicode UCS2 Little Endian
  4328.  
  4329.           So you can use DIR /XFER to get a preview of how each file in a
  4330.           selected group will be transferred. Everything to the right of
  4331.           the (B) or (T) is new. If FILE SCAN is OFF, you only get the
  4332.           (B) or (T) as before.
  4333.           
  4334.           Note: Big and Little Endian refer to the ordering of bytes
  4335.           within a computer word. Big Endian architecture is standard and
  4336.           is used on most non-PC computers. Little Endian architecture is
  4337.           used on PCs.
  4338.           
  4339.    To illustrate file-transfer with scanning, suppose you have a
  4340.    directory containing a mixture of text and binary files, and each text
  4341.    file can be 7-bit German ISO 646, 8-bit Latin-1, or Unicode in any of
  4342.    the following forms: UCS2 Little Endian, UCS2 Big Endian, or UTF8
  4343.    ([333]UTF-16 is not supported yet). Assuming all the built-in defaults
  4344.    are in effect, the following three commands do the job:
  4345.    
  4346.   set file char german   ; This sets the default for 7-bit text files
  4347.   set file char latin1   ; This sets the default for 8-bit text files
  4348.   send *
  4349.  
  4350.    Each file is sent in the appropriate mode (text or binary), with text
  4351.    files converted to the appropriate transfer character-set and labeled
  4352.    so the receiver can convert them according to its own local
  4353.    conventions.
  4354.    
  4355.    By the way, what if you want to inhibit character-set translation but
  4356.    still allow automatic text/binary mode switching? Previously, you
  4357.    could simply SET TRANSFER CHARACTER-SET TRANSPARENT. But now with file
  4358.    scanning, the file and transfer character-sets are set automatically
  4359.    per file. A new command was added for this purpose:
  4360.    
  4361.    SET TRANSFER TRANSLATION { ON, OFF }
  4362.           Enables and disables file-transfer character-set translation.
  4363.           It is enabled by default.
  4364.           
  4365.    When TRANSFER TRANSLATION is OFF but FILE SCAN is ON, files are still
  4366.    scanned to see if they are text or binary, but no character-set
  4367.    translation is done when they text: only the normal record-format
  4368.    conversion.
  4369.    
  4370.    Like all SET commands, SET TRANSFER TRANSLATION is global and
  4371.    persistent. You can also force a particular file-transfer command
  4372.    (SEND, MSEND, GET, RECEIVE, TRANSMIT, etc) to not translate without
  4373.    affecting the global translation settings by including the new
  4374.    /TRANSPARENT switch, e.g.
  4375.    
  4376.   send /transparent oofa.txt
  4377.  
  4378.    File scanning is also used in the TYPE command. The source file type
  4379.    and character set are determined as above, and then the file is
  4380.    automatically converted to your display character-set, line by line.
  4381.    In Kermit 95, the display character-set is Unicode, perhaps converted
  4382.    to your current console code page; in other versions of C-Kermit, it
  4383.    is your current file character-set. Thus if you have the following set
  4384.    appriately:
  4385.    
  4386.   SET FILE CHARACTER-SET (necessary in Unix but not K95)
  4387.   SET FILE DEFAULT 7BIT CHARACTER-SET
  4388.   SET FILE DEFAULT 8BIT CHARACTER-SET
  4389.  
  4390.    then you should be able to TYPE any text file and see something
  4391.    reasonable. For example, in Unix, if your DEFAULT 7BIT-CHARACTER-SET
  4392.    is ITALIAN and your DEFAULT 8BIT-CHARACTER-SET is LATIN1, and your
  4393.    FILE CHARACTER-SET is LATIN1, you can TYPE an Italian ISO 646 file, a
  4394.    Latin-1 file, or any kind of Unicode file, and have it translated
  4395.    automatically to Latin-1 for your display.
  4396.    
  4397.    In the GUI version of Kermit 95, you can see mixtures of many
  4398.    different scripts if the file is UTF8 or UCS2: Roman, Cyrillic,
  4399.    Hebrew, Greek, Armenian, Georgian, etc, all on the same screen at
  4400.    once.
  4401.    
  4402.    File scanning also adds a new criterion for file selection, i.e. to
  4403.    select only text (or binary) files. Several commands now include a new
  4404.    switch, /TYPE:{BINARY,TEXT,ALL}. BINARY means select only binary
  4405.    regular files (not directories). TEXT means select only text files.
  4406.    ALL means don't scan; select all files. Examples:
  4407.    
  4408.    SEND /TYPE:BINARY *.*
  4409.           Sends only binary files, skipping over text files.
  4410.           
  4411.    NOTE: File scanning is NOT done when using external protocols (because
  4412.    the external protocol programs, such as sz, are processing each file,
  4413.    not Kermit).
  4414.    
  4415.    DIRECTORY /TYPE:TEXT
  4416.           Lists only text files but not binary files.
  4417.           
  4418.    DELETE /TYPE:BINARY foo.*
  4419.           Deletes all foo.* files that are regular binary files but does
  4420.           not delete any text files.
  4421.           
  4422.    CHMOD /TYPE:BINARY 775 *
  4423.           (UNIX) Changes the permissions of all binary files to 775.
  4424.           
  4425.    When FILE SCAN is OFF and FILE PATTERNS are ON, behavior is as before
  4426.    with PATTERNS ON, but with some improvements:
  4427.    
  4428.      * Pathnames are now stripped prior to pattern matching.
  4429.      * Backup suffixes (like .~3~) are stripped prior to pattern
  4430.        matching.
  4431.        
  4432.    [ [334]Top ] [ [335]Contents ] [ [336]C-Kermit Home ] [ [337]Kermit
  4433.    Home ]
  4434.   __________________________________________________________________________
  4435.  
  4436. 5. FILE AND DIRECTORY NAMES CONTAINING SPACES
  4437.  
  4438.    Prior to the introduction of the graphical user interface (GUI), it
  4439.    was inconceivable that file or directory names could contain spaces,
  4440.    because space is a field delimiter in all command languages. GUIs,
  4441.    however, use dialog boxes for filenames, so there is never any
  4442.    question of distinguishing a filename from adjacent fields -- because
  4443.    there are no adjacent fields -- and therefore it has become quite
  4444.    common on computers that have GUIs to have file and directory names
  4445.    composed of multiple words. Of course this poses problems for command
  4446.    shells and other text-oriented programs.
  4447.    
  4448.    Most command shells address these problems by allowing such names to
  4449.    be enclosed in doublequotes, e.g.:
  4450.    
  4451.   cd "c:\Program Files"
  4452.  
  4453.    C-Kermit previously used braces for this:
  4454.    
  4455.   cd {c:\Program Files}
  4456.  
  4457.    which was not what most people expected. And even when braces were
  4458.    used, Kermit had difficulties with completion, file menus, and so
  4459.    forth, within braced fields.
  4460.    
  4461.    C-Kermit 8.0 allows either doublequotes or braces to be used for
  4462.    grouping:
  4463.    
  4464.   send "this file"
  4465.   send {this file}
  4466.   rename "this file" "that file"
  4467.   rename {this file} "that file"
  4468.   rename "this file" {that file}
  4469.   cd {Program Files}
  4470.   cd "Program Files"
  4471.  
  4472.    Note that the doublequotes or brackets must enclose the whole file or
  4473.    directory specification:
  4474.    
  4475.   "c:\My Directory"
  4476.  
  4477.    not:
  4478.    
  4479.   c:\"My Directory"
  4480.  
  4481.    In C-Kermit 8.0, you can also use completion on these filenames, in
  4482.    which case Kermit supplies the quotes (or braces) automatically.
  4483.    Example (in which the current directory contains only one file whose
  4484.    name starts with "th" and its full name is "this file" (without the
  4485.    quotes, but with the space)):
  4486.    
  4487.   cat th<Tab>
  4488.  
  4489.    Kermit repaints the filename field like this:
  4490.    
  4491.   cat "this file"
  4492.  
  4493.    That is, it backspaces over the original "th" and then writes the
  4494.    filename in doublequotes.
  4495.    
  4496.    If completion is only partial, Kermit still supplies the quotes, but
  4497.    in this case also beeps. To continue the filename, you must first
  4498.    backspace over the closing quote. The closing quote is supplied in
  4499.    this case to make sure that you can see the spaces, especially if they
  4500.    are trailing. For example, if the current directory contains two files
  4501.    whose names start with "th", and their fill names are "this file" and
  4502.    "this other file":
  4503.    
  4504.   cat th<Tab>
  4505.  
  4506.    Kermit prints:
  4507.    
  4508.   cat "this "<Beep>
  4509.  
  4510.    If it didn't print the closing quote, you would probably wonder why it
  4511.    was beeping.
  4512.    
  4513.    Also, if you begin a filename field with a doublequote or opening
  4514.    brace, now you can use completion or get ?-help; this was never
  4515.    possible before.
  4516.    
  4517.  C-Kermit>type "thi? Input file specification, one of the following:
  4518.    this file        this other file
  4519.  C-Kermit>type "thi_
  4520.  
  4521.    [ [338]Top ] [ [339]Contents ] [ [340]C-Kermit Home ] [ [341]Kermit
  4522.    Home ]
  4523.   __________________________________________________________________________
  4524.  
  4525. 6. OTHER COMMAND PARSING IMPROVEMENTS
  4526.  
  4527.   6.1. Grouping Macro Arguments
  4528.   
  4529.    Doublequotes now can be used in macro invocations to group arguments
  4530.    containing spaces, where previously only braces could be used:
  4531.    
  4532.   define xx show args
  4533.   xx one "this is two" three
  4534.  
  4535.    Result:
  4536.    
  4537.   Macro arguments at level 0 (\v(argc) = 4):
  4538.    \%0 = xx
  4539.    \%1 = one
  4540.    \%2 = this is two
  4541.    \%3 = three
  4542.  
  4543.    Also, you can now quote braces and quotes in macro args (this didn't
  4544.    work before). Examples:
  4545.    
  4546.   xx "{"  ; The argument is a single left brace
  4547.   xx {"}  ; The argument is a doublequote character
  4548.  
  4549.    In case this new behavior interferes with your scripts, you can
  4550.    restore the previous behavior with:
  4551.    
  4552.   SET COMMAND DOUBLEQUOTING OFF
  4553.  
  4554.   6.2. Directory and File Name Completion
  4555.   
  4556.    C-Kermit 8.0 also includes better completion for directory names, e.g.
  4557.    in the CD command. If the name typed so far uniquely matches a
  4558.    directory name, it is completed (as before), but now if the directory
  4559.    contains any subdirectories, completion is partial (allowing you to
  4560.    supply additional path segments without backspacing); otherwise it is
  4561.    complete.
  4562.    
  4563.    Completion has also been improved for file and directory names that
  4564.    contain not only spaces (as described above) but also "metacharacters"
  4565.    such as asterisk (*) and tilde (~): now the field is repainted if
  4566.    necessary. For example, if the current directory contains only one
  4567.    file whose name contains "blah", then in:
  4568.    
  4569.   type *blah<Tab>
  4570.  
  4571.    "*blah" is replaced by the filename. In earlier releases, the part
  4572.    typed so far was left on the command line (and in the history buffer),
  4573.    so even when the original command worked, the recalled version would
  4574.    not. Similarly for ~ (the nearly-universal Unix notation for
  4575.    username):
  4576.    
  4577.   type ~olga/x<Tab>
  4578.  
  4579.    is repainted as (e.g.):
  4580.    
  4581.   type /users/home/olga/x(Beep)
  4582.  
  4583.    Speaking of command history, the new SHOW HISTORY command shows your
  4584.    command history and recall buffer. SAVE COMMAND HISTORY saves it into
  4585.    a file of your choice.
  4586.    
  4587.   6.3. Passing Arguments to Command Files
  4588.   
  4589.    The method for passing arguments to command files has been improved.
  4590.    Prior to C-Kermit 7.0 there was no provision for doing this. In
  4591.    C-Kermit 7.0, the TAKE command was changed to allow arguments to be
  4592.    given after the filename:
  4593.    
  4594.   take commandfile arg1 arg2 ...
  4595.  
  4596.    This was accomplished by replacing the current \%1, \%2, etc, with the
  4597.    given arguments, since a new set of macro argument variables is
  4598.    created only when a macro is executed, not a command file. It is much
  4599.    more intuitive, however, if arguments to command files worked like
  4600.    those to macros: the command file sees the arguments as its own \%1,
  4601.    \%2, etc, but the caller's variables are not disturbed. C-Kermit 8.0
  4602.    accomplishes this by automatically creating an intermediate temporary
  4603.    macro to start the command file (if any arguments were given), thus
  4604.    creating a new level of arguments as expected.
  4605.    
  4606.   6.4. More-Prompting
  4607.   
  4608.    The familiar --more?-- prompt that appears at the end of each
  4609.    screenful of command-response output now accepts a new answer: G (Go)
  4610.    meaning "show all the rest without pausing and asking me any more
  4611.    questions". P (Proceed) is a synonym for G.
  4612.    
  4613.   6.5. Commas in Macro Definitions
  4614.   
  4615.    As noted in the [342]C-Kermit manual, comma is used to separate
  4616.    commands in a macro definition. Even when the macro is defined on
  4617.    multiple lines using curly-brace block-structure notation without
  4618.    commas, the definition is still stored internally as a comma-separated
  4619.    list of commands. Therefore special tricks are needed to include a
  4620.    comma in a command. The classic example is:
  4621.    
  4622.   define foo {
  4623.       (some command)
  4624.       if fail echo Sorry, blah failed...
  4625.   }
  4626.  
  4627.    This would result in Kermit trying to execute a "blah" command. This
  4628.    could always be handled by enclosing the text in braces:
  4629.    
  4630.   define foo {
  4631.       (some command)
  4632.       if fail echo {Sorry, blah failed...}
  4633.   }
  4634.  
  4635.    but doublequotes (more intuitive) should have worked too. Now they do:
  4636.    
  4637.   define foo {
  4638.       (some command)
  4639.       if fail echo "Sorry, blah failed..."
  4640.   }
  4641.  
  4642.   6.6. Arrow Keys
  4643.   
  4644.    As of version 8.0.201, C-Kermit on most platforms lets you access the
  4645.    command history buffer with arrow keys, just as you always could with
  4646.    control characters. The restrictions are:
  4647.    
  4648.     1. Only Up and Down arrow keys are accepted.
  4649.     2. Only 7-bit ANSI arrow-key sequences are understood (ESC followed
  4650.        by [ or uppercase letter O, followed by uppercase letter A or (up)
  4651.        B (down).
  4652.        
  4653.    This change was made to facilitate command recall in Linux-based PDAs
  4654.    that don't have a Control key, or at least not one that's easily (or
  4655.    always) accessible, such as the Sharp Zaurus SL5500.
  4656.    
  4657.    [ [343]Top ] [ [344]Contents ] [ [345]C-Kermit Home ] [ [346]Kermit
  4658.    Home ]
  4659.   __________________________________________________________________________
  4660.  
  4661. 7. NEW COMMANDS AND SWITCHES
  4662.  
  4663.    See [347]Section 4 for more about file scanning and the /TYPE: switch.
  4664.    
  4665.    ASK[Q] [ /TIMEOUT:number ] variable [ prompt ]
  4666.           The new optional /TIMEOUT: switch for ASK and ASKQ causes the
  4667.           command to time out and and fail if no response is given within
  4668.           the specified number of seconds, 1 or greater (0 or less means
  4669.           no timeout, wait forever). This works just like SET ASK-TIMER,
  4670.           except its effect is local to the ASK command with which it is
  4671.           given and it does not disturb the global ask timer setting.
  4672.           
  4673.    CAT filename
  4674.           Equivalent to TYPE /NOPAGE.
  4675.           
  4676.    CDUP
  4677.           Changes Kermit's local working directory to the parent of the
  4678.           current one. Equivalent to "cd .." in UNIX or Windows, "cd [-]"
  4679.           in VMS, "cd ^" in AOS/VS, etc; in other words, it's a
  4680.           platform-independent way of moving one level up in a directory
  4681.           tree.
  4682.           
  4683.    CHMOD [ switches ] permission files
  4684.           UNIX only. Sets file permissions for one or more files or
  4685.           directories. The permission must be given as an octal number,
  4686.           e.g. 664, 755. Switches: /DIRECTORIES, /FILES, /NOLIST, /PAGE,
  4687.           /DOTFILES, /LIST, /NOPAGE, /RECURSIVE, /TYPE:{TEXT,BINARY,ALL},
  4688.           /SIMULATE. The /TYPE: switch allows selection of only text or
  4689.           binary files. For example, if you have a mixture of source
  4690.           files and executables, you can use "chmod /files /type:text
  4691.           664" to give owner/group read/write and world read permission
  4692.           to the text files, and "chmod /files /type:binary 775" to give
  4693.           the same plus execute permission to the executables. Use
  4694.           /SIMULATE to see which files would be affected, without
  4695.           actually changing their permissions.
  4696.           
  4697.    CLEAR KEYBOARD-BUFFER
  4698.           Flushes any as-yet unread characters from the keyboard input
  4699.           buffer. Useful for flushing typeahead in scripts.
  4700.           
  4701.    COPY, RENAME, and TRANSLATE
  4702.           These commands now work on file groups if the target filename
  4703.           is a directory, e.g. "copy oofa.* ..", "rename * ~olga/tmp/"
  4704.           
  4705.    DELETE /ASK
  4706.           Asks permission to delete each file before deleting it. In
  4707.           C-Kermit 7.0, the answers were "yes" (or "ok") and "no".
  4708.           C-Kermit 8.0 adds "go" (meaning, delete all the rest without
  4709.           asking) and "quit" (cancel the DELETE command and return to the
  4710.           prompt).
  4711.           
  4712.    DELETE /DIRECTORIES
  4713.           Deletes not only files but also directories.
  4714.           
  4715.    DELETE /RECURSIVE
  4716.           Deletes all files that match the given file specification in
  4717.           the current (or given) directory and all directories beneath
  4718.           it.
  4719.           
  4720.    DELETE /SUMMARY
  4721.           Prints only the number of files deleted and total size freed,
  4722.           without listing each file.
  4723.           
  4724.    DELETE /TREE
  4725.           Shorthand for DELETE /RECURSIVE /DIRECTORIES /DOTFILES/.
  4726.           Equivalent to Windows DELTREE or Unix "rm -Rf". If no file
  4727.           specification is given, the contents of the current directory,
  4728.           plus all of its subdirectories and their contents, are deleted.
  4729.           
  4730.    DELETE /TYPE:BINARY
  4731.           Delete only regular binary files (requires FILE SCAN ON).
  4732.           
  4733.    DELETE /TYPE:TEXT
  4734.           Delete only regular text files (requires FILE SCAN ON).
  4735.           
  4736.    DIRECTORY /NORECURSIVE xxx
  4737.           If xxx is a directory name, forces listing of the directory
  4738.           itself rather than its contents.
  4739.           
  4740.    DIRECTORY /FOLLOWLINKS xxx
  4741.           (UNIX only) Tells the DIRECTORY command to follow symbolic
  4742.           links. This not the default because it can cause endless loops.
  4743.           
  4744.    DIRECTORY /NOFOLLOWLINKS xxx
  4745.           (UNIX only) Tells the DIRECTORY command not to follow symbolic
  4746.           links, but rather, merely to list them. This is the default.
  4747.           
  4748.    DIRECTORY /OUTPUT:filename
  4749.           Sends the results of the DIRECTORY command to the given file.
  4750.           
  4751.    DIRECTORY /SUMMARY
  4752.           Prints only the number of directories and files and the total
  4753.           size, without listing each file.
  4754.           
  4755.    DIRECTORY /TYPE:{TEXT,BINARY}
  4756.           Shows only files of the selected type, based on file scan.
  4757.           
  4758.    DIRECTORY /XFERMODE
  4759.           Now shows results of file scan (see [348]Section 4).
  4760.           
  4761.    GREP [ switches ] pattern files
  4762.           Similar to Unix grep command: displays file lines that match
  4763.           the given [349]pattern. Switches:
  4764.           
  4765.         /COUNT[:variable]
  4766.                 Don't show the matching lines, just tell how many lines
  4767.                 match. If a variable name is specified, the count is
  4768.                 stored in the given variable.
  4769.                 
  4770.         /DOTFILES
  4771.                 Include files whose names begin with dot.
  4772.                 
  4773.         /LINENUMBERS
  4774.                 Show line numbers of matching lines.
  4775.                 
  4776.         /NAMEONLY
  4777.                 only list the names of files that contain matching lines,
  4778.                 but not the lines themselves.
  4779.                 
  4780.         /NOBACKUP
  4781.                 Skip backup files.
  4782.                 
  4783.         /NOCASE
  4784.                 Ignore alphabetic case while pattern matching.
  4785.                 
  4786.         /NODOTFILES
  4787.                 skip files whose names start with dot (period).
  4788.                 
  4789.         /NOLIST
  4790.                 Suppress output but set SUCCESS or FAILURE according to
  4791.                 search result.
  4792.                 
  4793.         /NOMATCH
  4794.                 Look for lines that do not match the pattern.
  4795.                 
  4796.         /NOPAGE
  4797.                 Don't pause between screens of output.
  4798.                 
  4799.         /OUTPUT:filename
  4800.                 Write results into the given file.
  4801.                 
  4802.         /PAGE
  4803.                 Pause between screens of output.
  4804.                 
  4805.         /RECURSIVE
  4806.                 Search files in subdirectories too.
  4807.                 
  4808.         /TYPE:{TEXT,BINARY}
  4809.                 Search only files of the specified type.
  4810.                 
  4811.           Synonyms: FIND, SEARCH.
  4812.           
  4813.    HEAD [ switches ] filename
  4814.           Equivalent to TYPE /HEAD [ other-switches ] filename.
  4815.           
  4816.    HELP DATE
  4817.           Explains date-time formats, including timezone notation and
  4818.           delta times.
  4819.           
  4820.    HELP FIREWALLS
  4821.           Explains the firewall negotiation capabilities of your version
  4822.           of Kermit.
  4823.           
  4824.    LICENSE
  4825.           Displays the C-Kermit license.
  4826.           
  4827.    L-commands
  4828.           When Kermit has a connection to a Kermit or FTP server, file
  4829.           managment commands such as CD, DIRECTORY, and DELETE might be
  4830.           intended for the local computer or the remote server. C-Kermit
  4831.           8.0.200 and earlier always executes these commands on the local
  4832.           computer. If you want them executed by the remote server, you
  4833.           have to prefix them with REMOTE (e.g. REMOTE CD) or use special
  4834.           R-command aliases (e.g. RCD = REMOTE CD, RDIR = REMOTE DIR,
  4835.           etc). But this feels unnatural to FTP users, who expect
  4836.           unprefixed file management commands to be executed by the
  4837.           remote server, rather than locally. C-Kermit 8.0.201 adds
  4838.           automatic locus switching to present an FTP-like interface for
  4839.           FTP connections and the normal Kermit interface for Kermit
  4840.           connections, and a SET LOCUS command (described below) to
  4841.           control whether or how this is done. For when LOCUS is REMOTE,
  4842.           a new set of commands was added for local management: LCD
  4843.           (Local CD), LDIR (Local DIR), etc. These are described below
  4844.           under SET LOCUS.
  4845.           
  4846.    MOREfilename
  4847.           Equivalent to TYPE /PAGE.
  4848.           
  4849.    PROMPT [ text ]
  4850.           For use in a macro or command file: enters interactive command
  4851.           mode within the current context ([350]Section 8.1). If the
  4852.           optional text is included, the prompt is set to it. The text
  4853.           can include variables, functions, etc, as in the SET PROMPT
  4854.           command. They are evaluated each time the prompt is printed.
  4855.           Unlike the SET PROMPT command, the text argument applies only
  4856.           to the current command level. Thus you can have different
  4857.           prompts at different levels.
  4858.           
  4859.    SET ATTRIBUTE RECORD-FORMAT { ON, OFF }
  4860.           Allows control of the Kermit's Record-Format attribute. Set
  4861.           this to OFF in case incoming file are refused due to unknown or
  4862.           invalid record formats if you want to accept the file anyway
  4863.           (and, perhaps, postprocess it to fix its record format).
  4864.           
  4865.    SET EXIT HANGUP { OFF, ON }
  4866.           Normally ON, meaning that when Kermit exits, it also explicitly
  4867.           hangs up the current SET LINE / SET PORT serial port according
  4868.           to the current SET MODEM TYPE and SET MODEM HANGUP METHOD, and
  4869.           closes the port device if it was opened by Kermit in the first
  4870.           place (as opposed to inherited). SET EXIT HANGUP OFF tells
  4871.           Kermit not to do this. This can't prevent the operating system
  4872.           from closing the device when Kermit exits (and it's a "last
  4873.           close") but if the port or modem have been conditioned to
  4874.           somehow ignore the close and keep the connection open, at least
  4875.           Kermit itself won't do anything explicit to hang it up or close
  4876.           it.
  4877.           
  4878.    SET FILE EOF { CTRL-Z, LENGTH }
  4879.           Specifies the end-of-file detection method to be used by
  4880.           C-Kermit when sending and receiving text files, and in the TYPE
  4881.           and similar text-file oriented commands. The normal and default
  4882.           method is LENGTH. You can specify CTRL-Z when handling CP/M or
  4883.           MS-DOS format text files, in which a Ctrl-Z (ASCII 26)
  4884.           character within the file marks the end of the file.
  4885.           
  4886.    SET FILE LISTSIZE number
  4887.           Allocates space for the given number of filenames to be filled
  4888.           in by the wildcard expander. The current number is shown by
  4889.           SHOW FILE. If you give a command that includes a filename
  4890.           containing a wildcard (such as "*") that matches more files
  4891.           that Kermit's list has room for, you can adjust the list size
  4892.           with this command.
  4893.           
  4894.    SET FILE STRINGSPACE number
  4895.           Allocates space for the given amount of filename strings for
  4896.           use by the wildcard expander. The current number is shown by
  4897.           SHOW FILE. The number is the total number of bytes of all the
  4898.           file specifications that match the given wildcard.
  4899.           
  4900.      If you need to process a bigger list of files than your computer
  4901.      has memory for, you might be able use an external file list. The
  4902.      Kermit SEND and the FTP PUT and GET commands accept a /LISTFILE:
  4903.      switch, which gives the name of a file that contains the list of
  4904.      files to be transferred. Example for UNIX:
  4905.      
  4906.   !find . -print | grep / > /tmp/names
  4907.   ftp put /update /recursive /listfile:/tmp/names
  4908.  
  4909.    SET LOCUS { AUTO, LOCAL, REMOTE }
  4910.           Added in C-Kermit 8.0.201.   Sets the locus for unprefixed file
  4911.           management commands such as CD, DIRECTORY, MKDIR, etc. When
  4912.           LOCUS is LOCAL these commands act locally and a REMOTE (or R)
  4913.           prefix (e.g. REMOTE CD, RCD, RDIR) is required to send file
  4914.           management commands to a remote server. When LOCUS is REMOTE,
  4915.           an L prefix is required to issue local file management commands
  4916.           (e.g. LCD, LDIR). The word LOCAL can't be used as a prefix
  4917.           since it is already used for declaring local variables. LOCUS
  4918.           applies to all types of connections, and thus is orthogonal to
  4919.           SET GET-PUT-REMOTE, which selects between Kermit and FTP for
  4920.           remote file-transfer and management commands. The default LOCUS
  4921.           is AUTO, which means we switch to REMOTE whenever an FTP
  4922.           connection is made, and to LOCAL whenever a non-FTP connection
  4923.           is made, and switch back accordingly whenever a connnection is
  4924.           closed. So by default, Kermit behaves in its traditional manner
  4925.           unless you make an FTP connection, in which case it acts like a
  4926.           regular FTP client (but better :-)   LOCUS applies to the
  4927.           following commands:
  4928.           
  4929.   Unprefixed    Remote       Local        Description        
  4930.    CD (CWD)      RCD          LCD          Change (Working) Directory
  4931.    CDUP          RCDUP        LCDUP        CD Up
  4932.    PWD           RPWD         LPWD         Print Working Directory
  4933.    DIRECTORY     RDIR         LDIR         Request a directory listinga
  4934.    DELETE        RDEL         LDEL         Delete (a) file(s)
  4935.    RENEME        RREN         LREN         Rename a file
  4936.    MKDIR         RMKDIR       LMKDIR       Create a directory
  4937.    RMDIR         RRMDIR       LRMDIR       Remove a directory
  4938.  
  4939.    SET ROOT directory
  4940.           Like UNIX chroot, without requiring privilege. Sets the root
  4941.           for file access, does not allow reference to or creation of
  4942.           files outside the root, and can't be undone.
  4943.           
  4944.    SET TERMINAL . . .
  4945.           (See [351]Section 12.)
  4946.           
  4947.    SET TRANSFER MESSAGE [ text ]
  4948.           Sets an initial text message to be displayed in the
  4949.           file-transfer display. The transfer message is automatically
  4950.           deleted once used, so must be set each time a message a
  4951.           desired. Any variables in the message are evaluated at the time
  4952.           the SET command is given. If the optional text is omitted, any
  4953.           transfer message that is currently set is removed. Synonym: SET
  4954.           XFER MSG. SHOW TRANSFER displays it if it has been set but not
  4955.           yet used.
  4956.           
  4957.    SHOW COMMUNICATIONS
  4958.           In C-Kermit 8.0, SHOW COMMUNICATIONS, when given in remote mode
  4959.           (i.e. before any connection has been established), tells the
  4960.           typical dialout device name for the particular platform on
  4961.           which it's running (e.g. TXA0: for VMS, or /dev/cua0p0 for
  4962.           HP-UX). On Unix platforms, it also tells the name of the
  4963.           lockfile directory. This way, you have an idea of what the SET
  4964.           LINE device name should look like, and if the SET LINE command
  4965.           fails, you know the name of the directory or device that is
  4966.           protected against you.
  4967.           
  4968.    SHOW VARIABLES [ name [ name [ ... ] ] ]
  4969.           In C-Kermit 8.0.201 you can request values of a list of
  4970.           built-in (\v(xxx)) variables. Each name is a pattern, as
  4971.           before, but now it a free pattern rather than an anchored one
  4972.           (explained in [352]Section 8.12) so now "show var date time"
  4973.           shows the values of all variables whose names include the
  4974.           strings "date" or "time".
  4975.           
  4976.    TAIL [ switches ] filename
  4977.           Equivalent to TYPE /TAIL [ other-switches ] filename.
  4978.           
  4979.    TRANSMIT /NOECHO [ other switches ] filename
  4980.           The /NOECHO switch is equivalent to giving the command SET
  4981.           TRANSMIT ECHO OFF prior to the TRANSMIT command, except the
  4982.           swith affects only the command with which it was given and does
  4983.           not affect the prevailing global setting.
  4984.           
  4985.    TRANSMIT /NOWAIT [ other switches ] filename
  4986.           The /NOWAIT switch is equivalent to giving the command SET
  4987.           TRANSMIT PROMPT 0 prior to the TRANSMIT command, except the
  4988.           swith affects only the command with which it was given and does
  4989.           not affect the prevailing global setting.
  4990.           
  4991.    TRANSMIT /NOWAIT /NOECHO /BINARY [ other switches ] filename
  4992.           When the TRANSMIT command is given with the /NOWAIT, /NOECHO,
  4993.           and /BINARY switches, this activates a special "blast the whole
  4994.           file out the communications connection all at once" mode that
  4995.           Kermit didn't have prior to version 8.0. There has been
  4996.           increasing demand for this type of transmission with the advent
  4997.           of devices that expect image (e.g. .JPG) or sound (e.g. .MP3)
  4998.           files as raw input. The obvious question is: how does the
  4999.           receiving device know when it has the whole file? This depends
  5000.           on the device, of course; usually after a certain amount of
  5001.           time elapses with nothing arriving, or else when Kermit hangs
  5002.           up or closes the connection.
  5003.           
  5004.    TYPE /CHARACTER-SET:name
  5005.           Allows you to specify the character set in which the file to be
  5006.           typed is encoded.
  5007.           
  5008.    TYPE /NUMBER
  5009.           Adds line numbers.
  5010.           
  5011.    TYPE /OUTPUT:filename
  5012.           Sends the results of the TYPE command to the given file.
  5013.           
  5014.    TYPE /TRANSLATE-TO:name
  5015.           Used in conjunction with TYPE /CHARACTER-SET:xxx; allows you to
  5016.           specify the character set in which the file is to be displayed.
  5017.           
  5018.    TYPE /TRANSPARENT
  5019.           Used to disable character-set translation in the TYPE command,
  5020.           which otherwise can take place automatically based on file
  5021.           scanning, even when /CHARACTER-SET and /TRANSLATE-TO switches
  5022.           are not given.
  5023.           
  5024.    VOID text
  5025.           Parses the text, evaluating any backslash items in it (such as
  5026.           function calls) but doesn't do anything further, except
  5027.           possibly printing error messages. Useful for invoking functions
  5028.           that have side effects without using or printing their direct
  5029.           results, e.g. "void \fsplit(\%a,&a)".
  5030.           
  5031.   Symbolic Links in UNIX
  5032.   
  5033.    The UNIX versions of C-Kermit have had /FOLLOWLINKS and /NOFOLLOWLINKS
  5034.    switches added to several commands to control the treatment of
  5035.    symbolic links. Different commands deal differently with symbolic
  5036.    links:
  5037.    
  5038.    Kermit SEND, FTP MPUT
  5039.           /NOFOLLOWLINKS is the default, which means symbolic links are
  5040.           skipped entirely. The alternative, /FOLLOWLINKS, should be used
  5041.           with caution, since an innocent link might point to a whole
  5042.           file system, or it might cause a loop. There is no way in
  5043.           Kermit or FTP protocol to send the link itself. We either skip
  5044.           them or follow them; we can't duplicate them.
  5045.           
  5046.    DIRECTORY
  5047.           /NOFOLLOWLINKS is the default, which means the DIRECTORY
  5048.           command lists symbolic links in a way that shows they are
  5049.           links, but it does not follow them. The alternative,
  5050.           /FOLLOWLINKS, follows links and gives information about the
  5051.           linked-to directories and files.
  5052.           
  5053.    DELETE, RMDIR
  5054.           The DELETE command does not have link-specific switches. DELETE
  5055.           never follows links. If you tell Kermit to delete a symbolic
  5056.           link, it deletes the link itself, not the linked-to file. Ditto
  5057.           for RMDIR.
  5058.           
  5059.    COPY
  5060.           The COPY command behaves just like the UNIX cp command; it
  5061.           always follows links.
  5062.           
  5063.    RENAME
  5064.           The RENAME command behaves just like the UNIX mv command; it
  5065.           operates on links directly rather than following.
  5066.           
  5067.    [ [353]Top ] [ [354]Contents ] [ [355]C-Kermit Home ] [ [356]Kermit
  5068.    Home ]
  5069.   __________________________________________________________________________
  5070.  
  5071. 8. OTHER SCRIPTING IMPROVEMENTS
  5072.  
  5073.   8.1. Performance and Debugging
  5074.   
  5075.    A command cache for frequently used commands plus some related
  5076.    optimizations increases the speed of compute-bound scripts by anywhere
  5077.    from 50% to 1000%.
  5078.    
  5079.    The new PROMPT command can be used to set breakpoints for debugging
  5080.    scripts. If executed in a command file or macro, it gives you an
  5081.    interactive command prompt in the current context of the script, with
  5082.    all its variables, arguments, command stack, etc, available for
  5083.    examination or change, and the ability to resume the script at any
  5084.    point (END resumes it, Ctrl-C or STOP cancels it and returns to top
  5085.    level).
  5086.    
  5087.    The new Ctrl-C trapping feature ([357]Section 8.14) lets you intercept
  5088.    interruption of scripts. This can be used in combination with the
  5089.    PROMPT command to debug scripts. Example:
  5090.    
  5091. define ON_CTRLC {
  5092.     echo INTERRUPTED BY CTRL-C...
  5093.     echo The command stack has not yet been rolled back:
  5094.     show stack
  5095.     echo Type Ctrl-C again or use the END command to return to top level.
  5096.     prompt Debug>
  5097. }
  5098.  
  5099.    Adding this ON_CTRL definition to your script lets you interrupt it at
  5100.    any point and get prompt that is issued at the current command level,
  5101.    so you can query local variables, etc.
  5102.    
  5103.    [ [358]Top ] [ [359]Contents ] [ [360]C-Kermit Home ] [ [361]Kermit
  5104.    Home ]
  5105.      _________________________________________________________________
  5106.    
  5107.   8.2. Using Macros as Numeric Variables
  5108.   
  5109.    A macro is a way to assign a value to a name, and then use the name to
  5110.    refer to the value. Macros are used in two ways in Kermit: as
  5111.    "subroutines" or functions composed of Kermit commands, which are
  5112.    executed, or as variables to hold arbitrary values -- text, numbers,
  5113.    filenames, etc.
  5114.    
  5115.    When a macro is to be executed, its name is given as if it were a
  5116.    C-Kermit command, optionally preceded by the word "do". When a macro
  5117.    is used as a variable, it must be "escaped" with \m(xxx) (or
  5118.    equivalent function, e.g. \s(xxx), \:(xxx), \fdefinition(xxx)), where
  5119.    xxx is the macro name, for example:
  5120.    
  5121.   define filename /usr/olga/oofa.txt
  5122.   send \m(filename)
  5123.  
  5124.    Of course variables can also hold numbers:
  5125.    
  5126.   define size 17
  5127.   declare \&a[\m(size)]
  5128.   ...
  5129.   define index 3
  5130.   if ( == \m(index) 3 ) echo The third value is: \&a[\m(index)]
  5131.   evaluate index (\m(index) * 4)
  5132.   if ( > \m(index) \m(size) ) echo Out of range!
  5133.  
  5134.    But these are contexts in which only numbers are valid. C-Kermit 8.0
  5135.    has been changed to treat non-escaped non-numeric items in strictly
  5136.    numeric contexts as macro names. So it is now possible (but not
  5137.    required) to omit the \m(...) notation and just use the macro name in
  5138.    these contexts:
  5139.    
  5140.   define size 17
  5141.   declare \&a[size]
  5142.   ...
  5143.   define index 3
  5144.   if ( == index 3 ) echo The third value is: \&a[index]
  5145.   evaluate index (index * 4)
  5146.   if ( > index size ) echo Out of range!
  5147.  
  5148.    This is especially nice for loops that deal with arrays. Here, for
  5149.    example, is a loop that reverses the order of the elements in an
  5150.    array. Whereas formerly it was necessary to write:
  5151.    
  5152.   .\%n ::= \fdim(&a)
  5153.   for \%i 1 \%n/2 1 {
  5154.       .tmp := \&a[\%n-\%i+1]
  5155.       .\&a[\%n-\%i+1] := \&a[\%i]
  5156.       .\&a[\%i] := \m(tmp)
  5157.   }
  5158.  
  5159.    Recoding this to use macro names "i" and "n" instead of the backslash
  5160.    variables \%i and \%n, we have:
  5161.    
  5162.   .n ::= \fdim(&a)
  5163.   for i 1 n/2 1 {
  5164.       .tmp := \&a[n-i+1]
  5165.       .\&a[n-i+1] := \&a[i]
  5166.       .\&a[i] := \m(tmp)
  5167.   }
  5168.  
  5169.    which reduces the backslash count to less than half. The final
  5170.    statement in the loop could be written ".\&a[i] ::= tmp" if the array
  5171.    contained only numbers (since ::= indicates arithmetic expression
  5172.    evaluation).
  5173.    
  5174.    Also, now you can use floating-point numbers in integer contexts (such
  5175.    as array subscripts), in which case they are truncated to an integer
  5176.    value (i.e. the fractional part is discarded).
  5177.    
  5178.    Examples of numeric contexts include:
  5179.    
  5180.      * Array subscripts.
  5181.      * Any numeric function argument.
  5182.      * Right-hand side of ::= assignments.
  5183.      * EVALUATE command or \fevaluate() function expression.
  5184.      * The INCREMENT or DECREMENT by-value.
  5185.      * IF =, >, <, !=, >=, and <= comparands.
  5186.      * The IF number construct.
  5187.      * FOR-loop variables.
  5188.      * STOP, END, and EXIT status codes.
  5189.      * The INPUT timeout value.
  5190.      * PAUSE, WAIT, SLEEP, MSLEEP intervals.
  5191.      * The SHIFT argument.
  5192.      * Numeric switch arguments, e.g. TYPE /WIDTH:number, SEND
  5193.        /LARGER:number.
  5194.      * SCREEN MOVE-TO row and column number.
  5195.      * Various SET DIAL parameters (timeout, retry limit, etc).
  5196.      * Various SET SEND or RECEIVE parameters (packet length, window
  5197.        size, etc).
  5198.      * Various other SET parameters.
  5199.        
  5200.    and:
  5201.    
  5202.      * S-Expressions (explained in [362]Section 9).
  5203.        
  5204.    Macro names used in numeric contexts must not include mathematical
  5205.    operators. Although it is legal to create a macro called "foo+bar", in
  5206.    a numeric context this would be taken as the sum of the values of
  5207.    "foo" and "bar". Any such conflict can be avoided, of course, by
  5208.    enclosing the macro name in \m(...).
  5209.    
  5210.    [ [363]Top ] [ [364]Contents ] [ [365]C-Kermit Home ] [ [366]Kermit
  5211.    Home ]
  5212.      _________________________________________________________________
  5213.    
  5214.   8.3. New IF Conditions
  5215.   
  5216.    Several new IF conditions are available:
  5217.    
  5218.    IF DECLARED arrayname
  5219.           Explained in [367]Section 8.6.
  5220.           
  5221.    IF KBHIT
  5222.           Allows a script to test whether a key was pressed without
  5223.           actually trying to read it.
  5224.           
  5225.    IF KERBANG (Unix only)
  5226.           True if Kermit was started from a Kerbang script. This is
  5227.           useful for knowing how to interpret the \&@[] and \&_[]
  5228.           argument vector arrays.
  5229.           
  5230.    IF INTEGER n
  5231.           This is just a synonym for IF NUMERIC, which is true if n
  5232.           contains only digits (or, if n is a variable, its value
  5233.           contains only digits).
  5234.           
  5235.    By contrast, IF FLOAT n succeeds if n is a floating-point number OR an
  5236.    integer (or a variable with floating-point or integer value).
  5237.    Therefore, IF FLOAT should be used whenever any kind of number is
  5238.    acceptable, whereas IF INTEGER (or IF NUMERIC) when only an integer
  5239.    can be used.
  5240.    
  5241.    [ [368]Top ] [ [369]Contents ] [ [370]C-Kermit Home ] [ [371]Kermit
  5242.    Home ]
  5243.      _________________________________________________________________
  5244.    
  5245.   8.4. The ON_UNKNOWN_COMMAND Macro
  5246.   
  5247.    The new ON_UNKNOWN_COMMAND macro, if defined, is executed whenever you
  5248.    give a command that is not known to C-Kermit; any operands are passed
  5249.    as arguments. Here are some sample definitions:
  5250.    
  5251.   DEF ON_UNKNOWN_COMMAND telnet \%1 ; Treat unknown commands as hostnames
  5252.   DEF ON_UNKNOWN_COMMAND dial \%1   ; Treat unknown commands phone numbers
  5253.   DEF ON_UNKNOWN_COMMAND take \%1   ; Treat unknown commands as filenames
  5254.   DEF ON_UNKNOWN_COMMAND !\%*       ; Treat unknown commands as shell commands
  5255.  
  5256.    [ [372]Top ] [ [373]Contents ] [ [374]C-Kermit Home ] [ [375]Kermit
  5257.    Home ]
  5258.      _________________________________________________________________
  5259.    
  5260.   8.5. The SHOW MACRO Command
  5261.   
  5262.    The SHOW MACRO command has been changed to accept more than one macro
  5263.    name:
  5264.    
  5265.   (setq a 1 b 2 c 3)
  5266.   show mac a b c
  5267.   a = 1
  5268.   b = 2
  5269.   c = 3
  5270.  
  5271.    An exact match is required for each name (except that case doesn't
  5272.    matter). If you include wildcard characters, however, a pattern match
  5273.    is performed:
  5274.    
  5275.   show mac [a-c]*x
  5276.  
  5277.    shows all macros whose names start with a, b, or c, and end with x.
  5278.    
  5279.    [ [376]Top ] [ [377]Contents ] [ [378]C-Kermit Home ] [ [379]Kermit
  5280.    Home ]
  5281.      _________________________________________________________________
  5282.    
  5283.   8.6. Arrays
  5284.   
  5285.    A clarification regarding references to array names (as opposed to
  5286.    array elements): You can use array-name "abbreviations" like &a only
  5287.    in contexts that expect array names, like ARRAY commands or array-name
  5288.    function arguments such as the second argument of \fsplit(). In a
  5289.    LOCAL statement, however, you have to write \&a[], since "local &a"
  5290.    might refer to a macro named "&a".
  5291.    
  5292.    In function arguments, however, you MUST use the abbreviated form:
  5293.    \fsplit(\%a,&a) or \fsplit(\%a,&a[]). If you include the backslash (as
  5294.    in "\fsplit(\%a,\&a[])") a parse error occurs.
  5295.    
  5296.    Here are the new array-related commands:
  5297.    
  5298.    IF DECLARED arrayname
  5299.           Allows a script to test whether an array has been declared. The
  5300.           arrayname can be a non-array backslash variable such as \%1 or
  5301.           \m(name), in which case it is evaluated first, and the result
  5302.           is treated as the array name. Otherwise, arrayname is treated
  5303.           as in the ARRAY commands: it can be a, &a, &a[], \&a, \&a[],
  5304.           \&a[3], \&a[3:9], etc, with the appropriate results in each
  5305.           case. Synonym: IF DCL.
  5306.           
  5307.    UNDECLARE arrayname
  5308.           UNDECLARE is a new top-level command to undeclare an array.
  5309.           Previously this could only be done with "declare \&a[0]" (i.e.
  5310.           re-declare the array with a dimension of 0).
  5311.           
  5312.    ARRAY LINK linkname arrayname
  5313.           Creates a symbolic link from the array named by linkname (which
  5314.           must be the name of an array that is not yet declared in the
  5315.           current context) to the array named by arrayname (which must
  5316.           the name of a currently declared array that is not itself a
  5317.           link, or a variable containing the name of such an array). The
  5318.           two names indicate the same array: if you change an array
  5319.           element, the change is reflected in the link too, and vice
  5320.           versa. If you undeclare the link, the real array is unaffected.
  5321.           If you undeclare the real array, all links to it disappear. If
  5322.           you resize an array (directly or through a link), all links to
  5323.           it are updated automatically.
  5324.           
  5325.    Array links let you pass array names as arguments to macros. For
  5326.    example, suppose you had a program that needed to uppercase all the
  5327.    elements of different arrays at different times. You could write a
  5328.    macro to do this, with the array name as an argument. But without
  5329.    array links, there would be no way to refer to the argument array
  5330.    within the macro. Array links make it easy:
  5331.    
  5332.   define arrayupper {
  5333.       local \&e[] \%i
  5334.       array link \&e[] \%1
  5335.       for i 1 \fdim(&e) 1 { .\&e[i] := \fupper(\&e[i]) }
  5336.   }
  5337.   declare \&a[] = these are some words
  5338.   arrayupper &a
  5339.   show array &a
  5340.  
  5341.    The macro declares the array link LOCAL, which means it doesn't
  5342.    conflict with any array of the same name that might exist outside the
  5343.    macro, and that the link is destroyed automatically when the macro
  5344.    exits. This works, by the way, even if the link name and the macro
  5345.    argument name are the same, as long as the link is declared LOCAL.
  5346.    
  5347.    As noted, you can't make a link to a nonexistent array. So when
  5348.    writing a macro whose job is to create an array whose name is passed
  5349.    as an argument, you must declare the array first (the size doesn't
  5350.    matter as long as it's greater than 0). Example:
  5351.    
  5352.   define tryme {                ; Demonstration macro
  5353.       local \&e[]               ; We only need this inside the macro
  5354.       array link \&e[] \%1      ; Make local link
  5355.       shift                     ; Shift argument list
  5356.       void \fsplit(\%*,&e)      ; Split remainder of arg list into array
  5357.   }
  5358.   declare \&a[1]                ; Declare target array in advance
  5359.   tryme &a here are some words  ; Invoke the macro with array name and words
  5360.   show array a                  ; See the results
  5361.  
  5362.    One final improvement allows the macro itself to declare the array
  5363.    (this was not possible in earlier Kermit releases): if the array name
  5364.    in the DECLARE command is a variable (and not an array name), or
  5365.    includes variables, the resulting value is used as the array name. So:
  5366.    
  5367.   define tryme {                ; Demonstration macro
  5368.       declare \%1[1]            ; Preliminary declaration for target array
  5369.       local \&e[]               ; We only need this inside the macro
  5370.       array link \&e[] \%1      ; Make local link
  5371.       shift                     ; Shift argument list
  5372.       void \fsplit(\%*,&e)      ; Split remainder of arg list into array
  5373.   }
  5374.   tryme &a here are some words  ; Invoke the macro with array name and words
  5375.   show array a                  ; See the results
  5376.  
  5377.    The SHOW ARRAY command now indicates whether an array name is a link.
  5378.    
  5379.    Also see the descriptions of [380]\fjoin() and [381]\fsplit(), plus
  5380.    [382]Section 8.10 on the MINPUT command, which shows how an entire
  5381.    array (or segment of it) can be used as the MINPUT target list.
  5382.    
  5383.    [ [383]Top ] [ [384]Contents ] [ [385]C-Kermit Home ] [ [386]Kermit
  5384.    Home ]
  5385.      _________________________________________________________________
  5386.    
  5387.   8.7. New or Improved Built-in Variables and Functions
  5388.   
  5389.    The following new built-in variables are available:
  5390.    
  5391.   \v(buildid)       A date string like "20000808" indicating when C-Kermit was
  5392. built.
  5393.   \v(ftime)         Current time, secs since midnight, including fraction of se
  5394. cond.
  5395.   \v(iprompt)       The current SET PROMPT value
  5396.   \v(sexp)          The most recent S-Expression (see [387]Section 9)
  5397.   \v(sdepth)        The current S-Expression invocation depth ([388]Section 9)
  5398.   \v(svalue)        The value of the most recent S-Expression ([389]Section 9)
  5399.  
  5400.   \v(ftp_code)      Most recent FTP response code ([390]Section 3)
  5401.   \v(ftp_connected) FTP connection status ([391]Section 3)
  5402.   \v(ftp_cpl)       FTP Command Protection Level ([392]Section 3.2)
  5403.   \v(ftp_dpl)       FTP Data Protection Level ([393]Section 3.2)
  5404.   \v(ftp_getputremote) The current SET GET-PUT-REMOTE setting ([394]Section 3.8
  5405. )
  5406.   \v(ftp_host)      Name or IP address of FTP server ([395]Section 3)
  5407.   \v(ftp_loggedin)  FTP login status ([396]Section 3)
  5408.   \v(ftp_message)   Most recent FTP response message ([397]Section 3)
  5409.   \v(ftp_security)  FTP Security method ([398]Section 3.2)
  5410.   \v(ftp_server)    OS type of FTP server ([399]Section 3)
  5411.  
  5412.   \v(http_code)      Most recent HTTP response code
  5413.   \v(http_connected) HTTP connection status
  5414.   \v(http_host)      Name or IP address of HTTP server
  5415.   \v(http_message)   Most recent HTTP response message
  5416.   \v(http_security)  TLS cipher used to secure the HTTP session
  5417.  
  5418.   \v(hour)           Hour of the day, 0 to 23.
  5419.   \v(timestamp)      Equivalent to "\v(ndate) \v(time)".
  5420.  
  5421.    The following new or improved built-in functions are available:
  5422.    
  5423.   \fcmdstack()            Allows programmatic access to the command stack.
  5424.   \fcvtdate()             [400]Section 8.13
  5425.   \fdelta2secs()          [401]Section 8.13
  5426.   \fdostounixpath(s1)     Converts a DOS filename to Unix format.
  5427.   \fsplit()               Now allows grouping/nesting in source string.
  5428.   \fword()                Allows the same grouping and nesting.
  5429.   \fjoin(&a,s1,n1,n2)     Copies an array into a single string.
  5430.   \fsubstitute(s1,s2,s3)  Substitutes characters within a string.
  5431.   \freplace()             Has new 4th "occurrence" argument.
  5432.   \fcvtdate()             Now accepts several format options.
  5433.   \fsexpression()         Evaluates an S-Expression (explained in [402]Section
  5434. 9).
  5435.   \ftrim(), \fltrim()     Now trim CR and LF by default, as well as SP and Tab.
  5436.   \funixtodospath(s1)     Converts a Unix filename to DOS format.
  5437.   \fkeywordval(s1,c1)     Assigns values to keywords (macros) (explained below)
  5438. .
  5439.  
  5440.    Most functions that have "2" in their names to stand for the word "2"
  5441.    can now also be written with "to", e.g. "\fdelta2secs(),"
  5442.    \fdeltatosecs()."
  5443.    
  5444.   8.7.1. The \fkeywordval() Function
  5445.   
  5446.    \fkeywordval(s1,c1) is new. Given a string s1 of the form
  5447.    "name=value", it creates a macro with the given name and assigns it
  5448.    the given value. If no value appears after the equal sign, any
  5449.    existing macro of the given name is undefined. Blanks are
  5450.    automatically trimmed from around the name and value. The optional c1
  5451.    parameter is the assignment operator character, equal sign (=) by
  5452.    default. This function is handy for processing keyword parameters or
  5453.    any other form of parameter-value pair. Suppose, for example, you want
  5454.    to write a macro that accepts keyword parameters rather than
  5455.    positional ones:
  5456.    
  5457.   define MYDIAL {
  5458.       local \%i modem hangup method device speed number
  5459.       def number 5551234          ; Assign default parameter values
  5460.       def speed 57600
  5461.       def modem usrobotics
  5462.       def hangup rs232
  5463.       def method tone
  5464.       def country 1
  5465.       for \%i 1 \v(argc)-1 1 {    ; Parse any keyword parameters...
  5466.           if not \fkeywordval(\&_[\%i]) end 1 Bad parameter: "\&_[\%i]"
  5467.       }
  5468.       set dial country \m(country)
  5469.       set modem type \m(modem)
  5470.       set modem hang \m(hangup)
  5471.       set dial method \m(tone)
  5472.       set line \m(device)
  5473.       if fail stop 1
  5474.       set speed \m(speed)
  5475.       if fail stop 1
  5476.       show comm
  5477.       set dial display on
  5478.       dial \m(number)
  5479.       if success connect
  5480.   }
  5481.  
  5482.    In this example, all the defaults are set up inside the macro, and
  5483.    therefore it can be invoked with no parameters at all. But if you want
  5484.    to have the macro dial a different number, you can supply it as
  5485.    follows:
  5486.    
  5487.   mydial number=7654321
  5488.  
  5489.    You can supply any number of keyword parameters, and you can give them
  5490.    in any order:
  5491.    
  5492.   mydial number=7654321 hangup=modem speed=115200
  5493.  
  5494.   8.7.2. The \fsplit(), \fjoin(), and \fword() Functions
  5495.   
  5496.    \fjoin(&a,s1,n1,n2) is also new; it creates a string from an array (or
  5497.    a piece of one). &a is the name of the array (a range specifier can be
  5498.    included); s1 is a character or string to separate each element in the
  5499.    result string (can be omitted, in which case the elements are not
  5500.    separated at all), and n1 is a grouping mask, explained below. If s1
  5501.    is empty or not specified, the array elements are separated with
  5502.    spaces. If you want the elements concatenated with no separator,
  5503.    include a nonzero n2 argument. Given the array:
  5504.    
  5505.   declare \&a[] = 0 1 2 3 4 5 6 7 8 9
  5506.  
  5507.    you can get effects like this:
  5508.    
  5509.   \fjoin(&a)      0 1 2 3 4 5 6 7 8 9
  5510.   \fjoin(&a,:)    0:1:2:3:4:5:6:7:8:9
  5511.   \fjoin(&a,{,})  0,1,2,3,4,5,6,7,8,9
  5512.   \fjoin(&a,...)  0...1...2...3...4...5...6...7...8...9
  5513.   \fjoin(&a,,,1)  0123456789
  5514.  
  5515.    \fsplit(), \fword(), \fstripb(), and \fjoin() accept a "grouping mask"
  5516.    argument, n1, which is a number from 0 to 63, in which:
  5517.    
  5518.    1 = "" doublequotes
  5519.    2 = {} braces
  5520.    4 = '' singlequotes
  5521.    8 = () parentheses
  5522.   16 = [] square brackets
  5523.   32 = <> angle brackets
  5524.  
  5525.    These can be OR'd (added) together to make any number 0-63 (-1 is
  5526.    treated the same as 63, 0 means no grouping). If a bit is on, the
  5527.    corresponding kind of grouping is selected. (If more than 1 bit is set
  5528.    for \fjoin(), only the lowest-order one is used.)
  5529.    
  5530.    If you include the same character in the grouping mask and the include
  5531.    list, the grouping mask takes precedence. Example:
  5532.    
  5533.   def \%a  a "b c d" e
  5534.   \fsplit(\%a,&a[],,,-1)  = 3  <-- doublequote used for grouping
  5535.   \fsplit(\%a,&a[],,",-1) = 3  <-- doublequote still used for grouping
  5536.  
  5537.    Nesting of matched left and right grouping characters (parentheses,
  5538.    braces, and brackets, but not quotes) is recognized. Example:
  5539.    
  5540.   def \%a a (b c <d e [f g {h i} j k] l m> n o) p
  5541.   \fsplit(\%a,&a,,,0)  = 16 (no grouping)
  5542.   \fsplit(\%a,&a,,,2)  = 15 (braces only)
  5543.   \fsplit(\%a,&a,,,16) = 11 (square brackets only)
  5544.   \fsplit(\%a,&a,,,32) =  7 (angle brackets only)
  5545.   \fsplit(\%a,&a,,,63) =  3 (all)
  5546.   \fsplit(\%a,&a,,,-1) =  3 (all)
  5547.  
  5548.    \fsplit() and \fjoin() are "reciprocal" functions. You can split a
  5549.    string up into an array and join it back into a new string that is
  5550.    equivalent, as long as \fsplit() and \fjoin() are given equivalent
  5551.    grouping masks, except that the type of braces might change. Example:
  5552.    
  5553.   def \%a a {b c [d e] f g} "h i" j <k l> m
  5554.   echo STRING=[\%a]
  5555.   echo WORDS=\fsplit(\%a,&a,,,-1)
  5556.   show array a
  5557.   asg \%b \fjoin(&a,{ },2)
  5558.   echo JOIN  =[\%b]
  5559.   echo WORDS=\fsplit(\%b,&b,,,-1)
  5560.   show array b
  5561.  
  5562.    The arrays a and b are identical. The strings a and b are as follows:
  5563.    
  5564.   \%a: a {b c [d e] f g} "h i" j <k l> m
  5565.   \%b: a {b c [d e] f g} {h i} j {k l} m
  5566.  
  5567.    It is possible to quote separator grouping characters with backslash
  5568.    to override their grouping function. And of course to include
  5569.    backslash itself in the string, it must be quoted too. Furthermore,
  5570.    each backslash must be doubled, so the command parser will still pass
  5571.    one backslash to \fsplit() for each two that it sees. Here are some
  5572.    examples using \fsplit() with a grouping mask of 8 (treat parentheses
  5573.    as grouping characters).
  5574.    
  5575.   String                  Result
  5576.     a b c d e f             6
  5577.     a b\\ c d e f           5
  5578.     a b (c d e) f           4
  5579.     a b \\(c d e\\) f       6
  5580.     a b \\\\(c d e\\\\) f   7
  5581.  
  5582.    \fsplit() has also been changed to create its array (if one is given)
  5583.    each time it is called, so now it can be conveniently called in a loop
  5584.    without having to redeclare the array each time.
  5585.    
  5586.    Incidentally... Sometimes you might want to invoke \fsplit() in a
  5587.    situation where you don't care about its return value, e.g. when you
  5588.    just want to fill the array. Now you can "call" \fsplit() or any other
  5589.    function with the new [403]VOID command:
  5590.    
  5591.   void \fsplit(\%a,&a)
  5592.  
  5593.    \fsplit() and \fjoin() also accept a new, optional 6th argument, an
  5594.    options flag, a number that can specify a number of options. So far
  5595.    there is just one option, whose value is 1:
  5596.    
  5597.    separator-flag
  5598.           Normally separators are collapsed. So, for example,
  5599.           
  5600.   \fword(Three        little          words,2)
  5601.  
  5602.           returns "little" (the second word). Space is a separator, but
  5603.           there are multiple spaces between each word. If the value 1 is
  5604.           included in the option flag, however, each separator counts. If
  5605.           two separators are adjacent, an empty word is produced between
  5606.           them. This is useful for parsing (e.g.) comma-separated lists
  5607.           exported from databases or spreadsheets.
  5608.           
  5609.   8.7.3. The \fcmdstack() Function
  5610.   
  5611.    The new \fcmdstack() function gives access to the command stack:
  5612.    
  5613.    \fcmdstack(n1,n2)
  5614.           Arguments: n1 is the command stack level. If omitted, the
  5615.           current level, \v(cmdlevel), is used. n2 is a function code
  5616.           specifying the desired type of information:
  5617.           
  5618.  
  5619.   0 (default) = name of object at level n1.
  5620.   1 (nonzero) = object type (0 = prompt; 1 = command file; 2 = macro).
  5621.  
  5622.    The default for n2 is 0.
  5623.           
  5624.    The name associated with prompt is "(prompt)". Here's a loop that can
  5625.    be included in a macro or command file to show the stack (similar to
  5626.    what the SHOW STACK command does):
  5627.    
  5628.   for \%i \v(cmdlevel) 0 -1 {
  5629.       echo \%i. [\fcmdstack(\%i,1)] \fcmdstack(\%i,0)
  5630.   }
  5631.  
  5632.    In this connection, note that \v(cmdfile) always indicates the most
  5633.    recently invoked active command file (if any), even if that file is
  5634.    executing a macro. Similarly, \v(macro) indicates the most recently
  5635.    invoked macro (if any), even if the current command source is not a
  5636.    macro. The name of the "caller" of the currently executing object
  5637.    (command file or macro) is:
  5638.    
  5639.   \fcmdstack(\v(cmdlevel)-1)
  5640.  
  5641.    and its type is:
  5642.    
  5643.   \fcmdstack(\v(cmdlevel)-1,1)
  5644.  
  5645.    To find the name of the macro that invoked the currently executing
  5646.    object, even if one or more intermediate command files (or prompting
  5647.    levels) are involved, use a loop like this:
  5648.    
  5649.   for \%i \v(cmdlevel)-1 0 -1 {
  5650.       if = \fcmdstack(\%i,1) 2 echo CALLER = \fcmdstack(\%i,0)
  5651.   }
  5652.  
  5653.    Of course if you make a macro to do this, the macro must account for
  5654.    its own additional level:
  5655.    
  5656.   define CALLER {
  5657.       for \%i \v(cmdlevel)-2 0 -1 {
  5658.           if = \fcmdstack(\%i,1) 2 return \fcmdstack(\%i,0)
  5659.       }
  5660.       return "(none)"
  5661.   }
  5662.  
  5663.    The built-in variable \v(cmdsource) gives the current command source
  5664.    as a word ("prompt", "file", or "macro").
  5665.    
  5666.   8.7.4. The VOID Command
  5667.   
  5668.    VOID is like ECHO in that all functions and variables in its argument
  5669.    text are evaluated. but it doesn't print anything (except possibly an
  5670.    error message if a function was invocation contained or resulted in
  5671.    any errors). VOID sets FAILURE if it encounters any errors, SUCCESS
  5672.    otherwise.
  5673.    
  5674.    [ [404]Top ] [ [405]Contents ] [ [406]C-Kermit Home ] [ [407]Kermit
  5675.    Home ]
  5676.      _________________________________________________________________
  5677.    
  5678.   8.8. The RETURN and END Commands
  5679.   
  5680.    The execution of a macro is terminated in any of the following ways:
  5681.    
  5682.      * With an END [ number [ message ] ] command. If a number is given,
  5683.        the macro succeeds if the number is 0, and fails if it is not
  5684.        zero; if a number is not given, the macro succeeds.
  5685.      * With a STOP command, which works just like END except it peels
  5686.        back the command stack all the way to top level.
  5687.      * With a RETURN [ text ] command, in which case the macro always
  5688.        succeeds.
  5689.      * By running out of commands to execute, in which case the macro
  5690.        succeeds or fails according the most recently executed command
  5691.        that sets success or failure.
  5692.        
  5693.    The same considerations apply to command files invoked by the TAKE
  5694.    command.
  5695.    
  5696.    If a macro does not execute any commands that set success or failure,
  5697.    then invoking the macro does not change the current SUCCESS/FAILURE
  5698.    status. It follows, then, that the mere invocation of a macro does not
  5699.    change the SUCCESS/FAILURE status either. This makes it possible to
  5700.    write macros to react to the status of other commands (or macros), for
  5701.    example:
  5702.    
  5703.   define CHKLINE {
  5704.       if success end 0
  5705.       stop 1 SET LINE failed - please try another device.
  5706.   }
  5707.   set modem type usrobotics
  5708.   set line /dev/cua0
  5709.   chkline
  5710.   set speed 57600
  5711.   dial 7654321
  5712.  
  5713.    By the way, none of this is news. But it was not explicitly documented
  5714.    before, and C-Kermit 7.0 and earlier did not always handle the RETURN
  5715.    statement as it should have.
  5716.    
  5717.    [ [408]Top ] [ [409]Contents ] [ [410]C-Kermit Home ] [ [411]Kermit
  5718.    Home ]
  5719.      _________________________________________________________________
  5720.    
  5721.   8.9. UNDEFINing Groups of Variables
  5722.   
  5723.    The UNDEFINE command, which previously accepted one variable name, now
  5724.    accepts a list of them, and also accepts wildcard notation to allow
  5725.    deletion of variables that match a given pattern.
  5726.    
  5727.    UNDEFINE [ switches ] name [ name [ name [ ... ] ] ]
  5728.           Undefines the variables whose names are given. Up to 64 names
  5729.           may be given in one UNDEFINE command.
  5730.           
  5731.    If you omit the switches and include only one name, the UNDEFINE
  5732.    command works as before.
  5733.    
  5734.    Switches include:
  5735.    
  5736.    /MATCHING
  5737.           Specifies that the names given are to treated as patterns
  5738.           rather than literal variable names. Note: pattern matching
  5739.           can't be used with array references; use the ARRAY command to
  5740.           manipulate arrays and subarrays.
  5741.           
  5742.    /LIST
  5743.           List the name of each variable to be undefined, and whether it
  5744.           was undefined successfully ("ok" or "error"), plus a summary
  5745.           count at the end.
  5746.           
  5747.    /SIMULATE
  5748.           List the names of the variables that would be deleted without
  5749.           actually deleting them. Implies /LIST.
  5750.           
  5751.    The UNDEFINE command fails if there were any errors and succeeds
  5752.    otherwise.
  5753.    
  5754.    The new _UNDEFINE command is like UNDEFINE, except the names are
  5755.    assumed to be variable names themselves, which contain the names (or
  5756.    parts of them) of the variables to be undefined. For example, if you
  5757.    have the following definitions:
  5758.    
  5759.   define \%a foo
  5760.   define foo This is some text
  5761.  
  5762.    then:
  5763.    
  5764.   undef \%a
  5765.  
  5766.    undefines the variable \%a, but:
  5767.    
  5768.   _undef \%a
  5769.  
  5770.    undefines the macro foo.
  5771.    
  5772.    Normal Kermit patterns are used for matching; metacharacters include
  5773.    asterisk, question mark, braces, and square brackets. Thus, when using
  5774.    the /MATCHING switch, if the names of the macros you want to undefine
  5775.    contain any of these characters, you must quote them with backslash to
  5776.    force them to be taken literally. Also note that \%* is not the name
  5777.    of a variable; it is a special notation used within a macro for "all
  5778.    my arguments". The command "undef /match \%*" deletes all \%x
  5779.    variables, where x is 0..9 and a..z. Use "undef /match \%[0-9]" to
  5780.    delete macro argument variables or "undef /match \%[i-n]" to delete a
  5781.    range of \%x variables.
  5782.    
  5783.    [ [412]Top ] [ [413]Contents ] [ [414]C-Kermit Home ] [ [415]Kermit
  5784.    Home ]
  5785.      _________________________________________________________________
  5786.    
  5787.   8.10. The MINPUT Command
  5788.   
  5789.    The MINPUT command can be used to search the incoming data stream for
  5790.    several targets simultaneously. For example:
  5791.    
  5792.   MINPUT 8 one two three
  5793.  
  5794.    waits up to 8 seconds for one of the words "one", "two", or "three" to
  5795.    arrive. Words can be grouped to indicate targets that contain spaces:
  5796.    
  5797.   MINPUT 8 nineteeen twenty "twenty one"
  5798.  
  5799.    And of course you can also use variables in place of (or as part of)
  5800.    the target names:
  5801.    
  5802.   MINPUT 8 \%a \&x[3] \m(foo)
  5803.  
  5804.    Until now you had to know the number of targets in advance when
  5805.    writing the MINPUT statement. Each of the examples above has exactly
  5806.    three targets.
  5807.    
  5808.    But suppose your script needs to look for a variable number of
  5809.    targets. For this you can use arrays and \fjoin(), described in
  5810.    [416]Section 8.7. Any number of \fjoin() invocations can be included
  5811.    in the MINPUT target list, and each one is expanded into the
  5812.    appropriate number of separate targets each time the MINPUT command is
  5813.    executed. Example:
  5814.    
  5815.   declare \&a[10] = one two three
  5816.   minput 10 foo \fjoin(&a) bar
  5817.  
  5818.    This declares an array of ten elements, and assigns values to the
  5819.    first three of them. The MINPUT command looks for these three (as well
  5820.    as the words "foo" and "bar"). Later, if you assign additional
  5821.    elements to the array, the same MINPUT command also looks for the new
  5822.    elements.
  5823.    
  5824.    If an array element contains spaces, each word becomes a separate
  5825.    target. To create one target per array element, use \fjoin()'s
  5826.    grouping feature:
  5827.    
  5828.   dcl \&a[] = {aaa bbb} {ccc ddd} {xxx yyy zzz}
  5829.  
  5830.   minput 10 \fjoin(&a)     <-- 7 targets
  5831.   minput 10 \fjoin(&a,,2)  <-- 3 targets
  5832.  
  5833.    [ [417]Top ] [ [418]Contents ] [ [419]C-Kermit Home ] [ [420]Kermit
  5834.    Home ]
  5835.      _________________________________________________________________
  5836.    
  5837.   8.11. Learned Scripts
  5838.   
  5839.    C-Kermit now includes a simple script recorder that monitors your
  5840.    commands, plus your actions during CONNECT mode, and automatically
  5841.    generates a script program that mimics what it observed. You should
  5842.    think of this feature as a script-writing ASSISTANT since, as you will
  5843.    see [421]later in this section, the result generally needs some
  5844.    editing to make it both secure and flexible. The script recorder is
  5845.    controlled by the new LEARN command:
  5846.    
  5847.    LEARN [ /ON /OFF /CLOSE ] [ filename ]
  5848.           If you give a filename, the file is opened for subsequent
  5849.           recording. The /ON switch enables recording to the current file
  5850.           (if any); /OFF disables recording. /CLOSE closes the current
  5851.           script recording file (if any). If you give a filename without
  5852.           any switches, /ON is assumed.
  5853.           
  5854.    The /OFF and /ON switches let you turn recording off and on during a
  5855.    session without closing the file.
  5856.    
  5857.    When recording:
  5858.    
  5859.      * All commands that you type (or recall) at the prompt are recorded
  5860.        in the file except:
  5861.           + LEARN commands are not recorded.
  5862.           + The CONNECT command is not recorded.
  5863.           + The TELNET command is converted to SET HOST /NETWORK:TCP.
  5864.      * Commands obtained from macros or command files are not recorded.
  5865.      * During CONNECT:
  5866.           + Every line you type is converted to an OUTPUT command.
  5867.           + The last prompt before any line you type becomes an INPUT
  5868.             command.
  5869.           + Timeouts are calculated automatically for each INPUT command.
  5870.           + A PAUSE command is inserted before each OUTPUT command just
  5871.             to be safe.
  5872.        
  5873.    Thus the script recorder is inherently line-oriented. It can't be used
  5874.    to script character-oriented interactions like typing Space to a
  5875.    "More?" prompt or editing a text file with VI or EMACS.
  5876.    
  5877.    But it has advantages too; for example it takes control characters
  5878.    into account that might not be visible to you otherwise, and it
  5879.    automatically converts control characters in both the input and output
  5880.    streams to the appropriate notation. It can tell, for example that the
  5881.    "$ " prompt on the left margin in UNIX is really {\{13}\{10}$ },
  5882.    whereas in VMS it might be {\{13}\{10}\{13}$ }. These sequences are
  5883.    detected and recorded automatically.
  5884.    
  5885.    A learned script should execute correctly when you give a TAKE command
  5886.    for it. However, it is usually appropriate to edit the script a bit.
  5887.    The most important change would be to remove any passwords from it.
  5888.    For example, if the script contains:
  5889.    
  5890.   INPUT 9 {\{13}\{10}Password: }
  5891.   IF FAIL STOP 1 INPUT timeout
  5892.   PAUSE 1
  5893.   OUTPUT bigsecret\{13}
  5894.  
  5895.    you should replace this by something like:
  5896.    
  5897.   INPUT 9 {\{13}\{10}Password: }
  5898.   IF FAIL STOP 1 INPUT timeout
  5899.   ASKQ pswd Please type your password:
  5900.   PAUSE 1
  5901.   OUTPUT \m(pswd)\{13}
  5902.  
  5903.    The LEARN command can't do this for you since it knows nothing about
  5904.    "content"; it only knows about lines and can't be expected to parse or
  5905.    understand them -- after all, the Password prompt might be in some
  5906.    other language. So remember: if you use to LEARN command to record a
  5907.    login script, be sure edit the resulting file to remove any passwords.
  5908.    Also be sure to delete any backup copies your editor or OS might have
  5909.    made of the file.
  5910.    
  5911.    Other manual adjustments might also be appropriate:
  5912.    
  5913.      * If the target of an INPUT command can vary, you can replace the
  5914.        INPUT command with MINPUT and the appropriate target list, and/or
  5915.        the target with a \fpattern(). For example, suppose you are
  5916.        dialing a number that can be answered by any one of 100 terminal
  5917.        servers, whose prompts are ts-00>, ts-01>, ts-02>, ... ts-99>. The
  5918.        script records a particular one of these, but you want it to work
  5919.        for all of them, so change (e.g.):
  5920.  
  5921.   INPUT 10 ts-23>  ; or whatever
  5922.        to:
  5923.  
  5924.   INPUT 10 \fpattern(ts-[0-9][0-9]>)
  5925.      * The INPUT timeout values are conservative, but they are based only
  5926.        on a single observation; you might need to tune them.
  5927.      * The PAUSE commands might not be necessary, or the PAUSE interval
  5928.        might need adjustment.
  5929.      * In case you made typographical errors during recording, they are
  5930.        incorporated in your script; you can edit them out if you want to.
  5931.        
  5932.    Here is a sample script generated by Kermit ("learn vms.ksc") in which
  5933.    a Telnet connection is made to a VMS computer, the user logs in,
  5934.    starts Kermit on VMS, sends it a file, and then logs out:
  5935.    
  5936.   ; Scriptfile: vms.ksc
  5937.   ; Directory:  /usr/olga
  5938.   ; Recorded:   20001124 15:21:23
  5939.  
  5940.   SET HOST /NETWORK:TCP vms.xyzcorp.com
  5941.   IF FAIL STOP 1 Connection failed
  5942.  
  5943.   INPUT 7 {\{13}\{10}\{13}Username: }
  5944.   IF FAIL STOP 1 INPUT timeout
  5945.   PAUSE 1
  5946.   OUTPUT olga\{13}
  5947.   INPUT 3 {\{13}\{10}\{13}Password: }
  5948.   IF FAIL STOP 1 INPUT timeout
  5949.   PAUSE 1
  5950.   OUTPUT secret\{13}
  5951.   INPUT 18 {\{13}\{10}\{13}$ }
  5952.   IF FAIL STOP 1 INPUT timeout
  5953.   PAUSE 1
  5954.   OUTPUT set default [.incoming]\{13}
  5955.   INPUT 12 {\{13}\{10}\{13}$ }
  5956.   IF FAIL STOP 1 INPUT timeout
  5957.   PAUSE 1
  5958.   OUTPUT kermit\{13}
  5959.   INPUT 15 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>}
  5960.   IF FAIL STOP 1 INPUT timeout
  5961.   PAUSE 1
  5962.   OUTPUT receive\{13}
  5963.   send myfile.txt
  5964.  
  5965.   INPUT 18 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>}
  5966.   IF FAIL STOP 1 INPUT timeout
  5967.   PAUSE 1
  5968.   OUTPUT exit\{13}
  5969.   INPUT 6 {\{13}\{10}\{13}$ }
  5970.   IF FAIL STOP 1 INPUT timeout
  5971.   PAUSE 1
  5972.   OUTPUT logout\{13}
  5973.   close
  5974.   exit
  5975.  
  5976.    The commands generated by Kermit during CONNECT (INPUT, IF FAIL,
  5977.    PAUSE, and OUTPUT) have uppercase keywords; the commands typed by the
  5978.    user are in whatever form the user typed them (in this case,
  5979.    lowercase).
  5980.    
  5981.    [ [422]Top ] [ [423]Contents ] [ [424]C-Kermit Home ] [ [425]Kermit
  5982.    Home ]
  5983.      _________________________________________________________________
  5984.    
  5985.   8.12. Pattern Matching
  5986.   
  5987.    A pattern is a character string that is used to match other strings.
  5988.    Patterns can contain metacharacters that represent special actions
  5989.    like "match any single character", "match zero or more characters",
  5990.    "match any single character from a list", and so on. The best known
  5991.    application of patterns is in file specifications that contain
  5992.    wildcards, as in "send *.txt", meaning "send all files whose names end
  5993.    with .txt".
  5994.    
  5995.    Patterns are also used in increasingly many other ways, to the extent
  5996.    it is useful to point out certain important distinctions in the ways
  5997.    in which they are used:
  5998.    
  5999.    Anchored Patterns
  6000.           If an anchored pattern does not begin with "*", it must match
  6001.           the beginning of the string, and if it does not end with "*",
  6002.           it must match the end of the string. For example, the anchored
  6003.           pattern "abc" matches only the string "abc", not "abcde" or
  6004.           "xyzabc" or "abcabc". The anchored pattern "abc*" matches any
  6005.           string that starts with "abc"; the anchored pattern "*abc"
  6006.           matches any string that ends with "abc"; the anchored pattern
  6007.           "*abc*" matches any string that contains "abc" (which including
  6008.           any that start and/or end with it).
  6009.           
  6010.    Floating Patterns
  6011.           A floating pattern matches any string that contains a substring
  6012.           that matches the pattern. In other words, a floating pattern
  6013.           has an implied "*" and the beginning and end. You can anchor a
  6014.           floating pattern to the beginning by starting it with "^", and
  6015.           you can anchor it to the end by ending it with "$" (see
  6016.           examples below).
  6017.           
  6018.    Wildcards
  6019.           A wildcard is an anchored pattern that has the additional
  6020.           property that "*" does not match directory separators.
  6021.           
  6022.    This terminology lets us describe Kermit's commands with a bit more
  6023.    precision. When a pattern is used for matching filenames, it is a
  6024.    wildcard, except in the TEXT-PATTERNS and BINARY-PATTERNS lists and
  6025.    /EXCEPT: clauses, in which case directory separators are not
  6026.    significant (for example, a BINARY-PATTERN of "*.exe" matches any file
  6027.    whose name ends in .exe, no matter how deeply it might be buried in
  6028.    subdirectories. When Kermit parses a file specification directly,
  6029.    however, it uses the strict wildcard definition. For example, "send
  6030.    a*b" sends all files whose names start with "a" and end with "b" in
  6031.    the current directory, and not any files whose names end with "b" that
  6032.    happen to be in subdirectories whose names start with "a". And as
  6033.    noted, wildcards are anchored, so "delete foo" deletes the file named
  6034.    "foo", and not all files whose names happen to contain "foo".
  6035.    
  6036.    Most other patterns are anchored. For example:
  6037.    
  6038.   if match abc bc ...
  6039.  
  6040.    does not succeed (and you would be surprised if it did!). In fact, the
  6041.    only floating patterns are the ones used by commands or functions that
  6042.    search for patterns in files, arrays, or strings. These include:
  6043.    
  6044.      * The GREP and TYPE /MATCH commands.
  6045.      * The \fsearch(), \frsearch(), and \farraylook() functions.
  6046.        
  6047.    Thus these are the only contexts in which explicit anchors ("^" and
  6048.    "$") may be used:
  6049.    
  6050.    grep abc *.txt
  6051.           Prints all lines containing "abc" in all files whose names end
  6052.           with ".txt".
  6053.           
  6054.    grep ^abc *.txt
  6055.           Prints all lines that start with "abc" in all ".txt" files.
  6056.           
  6057.    grep abc$ *.txt
  6058.           Prints all lines that end with "abc" in all ".txt" files.
  6059.           
  6060.    grep ^a*z$ *.txt
  6061.           Prints all lines that start with "a" and end with "z" in all
  6062.           ".txt" files.
  6063.           
  6064.    Similarly for TYPE /PAGE, /fsearch(), /frsearch(), and \farraylook().
  6065.    
  6066.    Here is a brief summary of anchored and floating pattern equivalences:
  6067.    
  6068.   Anchored   Floating
  6069.     abc       ^abc$
  6070.     *abc      abc$
  6071.     abc*      ^abc
  6072.     *abc*     abc
  6073.  
  6074.    [ [426]Top ] [ [427]Contents ] [ [428]C-Kermit Home ] [ [429]Kermit
  6075.    Home ]
  6076.      _________________________________________________________________
  6077.    
  6078.   8.13. Dates and Times
  6079.   
  6080.    C-Kermit's comprehension of date-time formats is considerably expanded
  6081.    in version 8.0. Any command that reads dates, including the DATE
  6082.    command itself, or any switch, such as the /BEFORE: and /AFTER:
  6083.    switches, or any function such as \fcvtdate(), now can understand
  6084.    dates and times expressed in any ISO 8601 format, in Unix "asctime"
  6085.    format, in FTP MDTM format, and in practically any format used in RFC
  6086.    822 or RFC 2822 electronic mail, with or without timezones, and in a
  6087.    great many other formats as well. HELP DATE briefly summarizes the
  6088.    acceptable date-time formats.
  6089.    
  6090.    Furthermore, C-Kermit 8.0 includes a new and easy-to-use form of
  6091.    date-time arithmetic, in which any date or time can be combined with a
  6092.    "delta time", to add or subtract the desired time interval (years,
  6093.    months, weeks, days, hours, minutes, seconds) to/from the given date.
  6094.    And new functions are available to compare dates and to compute their
  6095.    differences.
  6096.    
  6097.    As you can imagine, all this requires quite a bit of "syntax". The
  6098.    basic format is:
  6099.    
  6100.   [ date ] [ time ] [ delta ]
  6101.  
  6102.    Each field is optional, but in most cases (depending on the context)
  6103.    there must be at least one field. If a date is given, it must come
  6104.    first. If no date is given, the current date is assumed. If no time is
  6105.    given, an appropriate time is supplied depending on whether a date was
  6106.    supplied. If no delta is given, no arithmetic is done. If a delta is
  6107.    given without a date or time, the current date and time are used as
  6108.    the base.
  6109.    
  6110.    Date-time-delta fields are likely to contain spaces (although they
  6111.    need not; space-free forms are always available). Therefore, in most
  6112.    contexts -- and notably as switch arguments -- date-time information
  6113.    must be enclosed in braces or doublequotes, for example:
  6114.    
  6115.   send /after:"8-Aug-2001 12:00 UTC" *.txt
  6116.  
  6117.    Kermit's standard internal format for dates and times is:
  6118.    
  6119.   yyyymmdd hh:mm:ss
  6120.  
  6121.    for example:
  6122.    
  6123.   20010208 10:28:01
  6124.  
  6125.    Date-times can always be given in this format. yyyy is the 4-digit
  6126.    year, mm is the two-digit month (1-12; supply leading zero for
  6127.    Jan-Sep), dd is the 2-digit day (leading zero for 1-9), hh is the hour
  6128.    (0-23), mm the minute (0-59), ss the second (0-59), each with leading
  6129.    zero if less than the field width. The date and time can be separated
  6130.    by a space, an underscore, a colon, or the letter T. The time is in
  6131.    24-hour format. Thus the various quantites are at the following fixed
  6132.    positions:
  6133.    
  6134. Position  Contents                    
  6135.    1-4    Year   (4 digits, 0000-9999)
  6136.    5-6    Month  (2 digits, 1-12)
  6137.    7-8    Day    (2 digits, 1-31)
  6138.    9      Date-Time Separator (space, :, _, or the letter T)
  6139.   10-11   Hour   (2 digits, 0-23)
  6140.   12      Hour-Minute Separator (colon)
  6141.   13-14   Minute (2 digits, 0-59)
  6142.   15      Minute-Second Separator (colon)
  6143.   16-17   Second (2 digits, 0-59)
  6144.  
  6145.    Example:
  6146.    
  6147.   19800526 13:07:12  26 May 1980, 13:07:12 (1:07:12PM)
  6148.  
  6149.    This is the format produced by the DATE command and by any function
  6150.    that returns a date-time. It is suitable for lexical comparison and
  6151.    sorting, and for use as a date-time in any Kermit command. When this
  6152.    format is given as input to a command or function, various date-time
  6153.    separators (as noted) are accepted:
  6154.    
  6155.   19800526 13:07:12  26 May 1980, 13:07:12 (1:07:12PM)
  6156.   20010208_10:28:35  2 February 2001, 10:28:35 AM
  6157.   18580101:12:00:00  1 January 1858, noon
  6158.   20110208T00:00:00  2 February 2011, midnight
  6159.  
  6160.    Certain other special date-time formats that are encountered on
  6161.    computer networks are recognized:
  6162.    
  6163.    Asctime Format
  6164.           
  6165.    This is a fixed format used by Unix, named after Unix's asctime()
  6166.           ("ASCII time") function. It is always exactly 24 characters
  6167.           long. Example: Fri Aug 10 16:38:01 2001
  6168.           
  6169.    Asctime with Timezone
  6170.           
  6171.    This is like Asctime format, but includes a 3-character timezone
  6172.           between the time and year. It is exactly 28 characters long.
  6173.           Example: Fri Aug 10 16:38:01 GMT 2001
  6174.           
  6175.    E-Mail Format
  6176.           E-mail date-time formats are defined in [430]RFC 2822 with a
  6177.           fair amount of flexibility and options. The following examples
  6178.           are typical of e-mails and HTTP (web-page) headers:
  6179.           
  6180.  
  6181.   Sat, 14 Jul 2001 11:49:29                (No timezone)
  6182.   Fri, 24 Mar 2000 14:19:59 EST            (Symbolic timezone)
  6183.   Tue, 26 Jun 2001 10:19:45 -0400 (EDT)    (GMT Offset + comment)
  6184.  
  6185.    FTP MDTM Format
  6186.           
  6187.    This is the date-time format supplied by FTP servers that support the
  6188.           (not yet standard but widely used nevertheless) MDTM command,
  6189.           by which the FTP client asks for a file's modification time:
  6190.           
  6191.   yyyymmddhhmmss[.ffff]
  6192.  
  6193.           where yyyy is the 4-digit year, mm is the 2-digit month, and so
  6194.           on, exactly 14 digits long. An optional fractional part
  6195.           (fraction of second) may also be included, separated by a
  6196.           decimal point (period). Kermit rounds to the nearest second.
  6197.           Example:
  6198.           
  6199.   20020208102835.515                       (8 February 2002 10:28:36 AM)
  6200.  
  6201.     8.13.1. The Date
  6202.     
  6203.    The date, if given, must precede the time and/or delta, and can be in
  6204.    many, many formats. For starters, you can use several symbolic date
  6205.    names in place of actual dates:
  6206.    
  6207.    NOW
  6208.           This is replaced by the current date and time. The time can not
  6209.           be overriden (if you want to supply a specific time, use TODAY
  6210.           rather than NOW).
  6211.           
  6212.    TODAY
  6213.           This is replaced by the current date and a default time of
  6214.           00:00:00 is supplied, but can be overridden by a specific time;
  6215.           for example, if today is 8 February 2002, then "TODAY" is
  6216.           "20020802 00:00:00" but "TODAY 10:28" is "20020802 10:28:00".
  6217.           
  6218.    TOMORROW
  6219.           Like TODAY, but one day later (if today is 8 February 2002,
  6220.           then "TOMORROW" is "20020803 00:00:00" but "TOMORROW 16:30" is
  6221.           "20020803 16:30:00").
  6222.           
  6223.    YESTERDAY
  6224.           Like TODAY, but one day earlier.
  6225.           
  6226.    MONDAY, TUESDAY, WEDNESDAY, ..., SUNDAY
  6227.           The date on the given day of the week, today or later. A
  6228.           default time of 00:00:00 is supplied but can be overridden.
  6229.           Example: "SATURDAY 12:00" means next Saturday (or today, if
  6230.           today is Saturday) at noon.
  6231.           
  6232.    You can give an explicit date in almost any conceivable format, but
  6233.    there are some rules:
  6234.    
  6235.      * If a date is given, it must have three fields: day, month, and
  6236.        year; the order can vary (except that the month can not be last).
  6237.      * If names are used for days, months, etc, they must be English.
  6238.      * The year must lie between 0000 and 9999, inclusive.
  6239.      * All calendar calculations use Gregorian dating, so calculated
  6240.        dates for years prior to 1582 (or later, depending on the country)
  6241.        will not agree with historical dates. Other forms of dating (e.g.
  6242.        Hebrew, Chinese) are not supported.
  6243.        
  6244.    Various date-field separators are accepted: hyphen, slash, space,
  6245.    underscore, period. The same field separator (if any) must be used in
  6246.    both places; for example 18-Sep-2001 but not 18-Sep/2001. Months can
  6247.    be numeric (1-12) or English names or abbreviations. Month name
  6248.    abbreviations are normally three letters, e.g. Apr, May, Jun, Jul.
  6249.    Capitalization doesn't matter.
  6250.    
  6251.    Here are a few examples:
  6252.    
  6253.   18 Sep 2001                              (English month, abbreviated)
  6254.   18 September 2001                        (English month, spelled out)
  6255.   2001 Sept 18                             (Year, month, day)
  6256.   18-Sep-2001                              (With hyphens)
  6257.   18/09/2001                               (All numeric with slashes)
  6258.   18.09.2001                               (Ditto, with periods)
  6259.   18_09_2001                               (Ditto, with underscores)
  6260.   09/18/2001                               (See below)
  6261.   2001/09/18                               (See below)
  6262.   September 18, 2001                       (Correspondence style)
  6263.   Sep-18-2001                              (Month-day-year)
  6264.   20010918                                 (Numeric, no separators)
  6265.  
  6266.    You can also include the day of the week with a specific date, in
  6267.    which case it is accepted (if it is a valid day name), but not
  6268.    verified to agree with the given date:
  6269.    
  6270.   Tue, 18 Sep 2001                         (Abbreviated, with comma)
  6271.   Tue,18 Sep 2001                          (Comma but no space)
  6272.   Tue 18 Sep 2001                          (Abbreviated, no comma)
  6273.   Tuesday 18 Sep 2001                      (Spelled out)
  6274.   Tuesday, 18 Sep 2001                     (etc)
  6275.   Friday, 18 Sep 2001                      (Accepted even if not Friday)
  6276.  
  6277.    In all-numeric dates with the year last, such as 18/09/2001, Kermit
  6278.    identifies the year because it's 4 digits, then decides which of the
  6279.    other two numbers is the month or day based on its value. If both are
  6280.    12 or less and are unequal, the date is ambiguous and is rejected. In
  6281.    all-numeric dates with the year first, the second field is always the
  6282.    month and the third is the day. The month never comes last. A date
  6283.    with no separators is accepted only if it is all numeric and has
  6284.    exactly eight digits, and is assumed to be in yyyymmdd format.
  6285.    
  6286.   20010918                                 (18-Sep-2001 00:00:00)
  6287.  
  6288.    or 14 digits (as in FTP MDTM format):
  6289.    
  6290.   20010918123456                           (18-Sep-2001 12:34:56)
  6291.  
  6292.    You can always avoid ambiguity by putting the year first, or by using
  6293.    an English, rather than numeric, month. A date such as 09/08/2001
  6294.    would be ambiguous but 2001/09/08 is not, nor is 09-Aug-2001.
  6295.    
  6296.    Until the late 1990s, it was common to encounter 2-digit years, and
  6297.    these are found to this day in old e-mails and other documents. Kermit
  6298.    accepts these dates if they have English months, and interprets them
  6299.    according to the windowing rules of [431]RFC 2822: "If a two digit
  6300.    year is encountered whose value is between 00 and 49, the year is
  6301.    interpreted by adding 2000, ending up with a value between 2000 and
  6302.    2049. If a two digit year is encountered with a value between 50 and
  6303.    99, or any three digit year is encountered, the year is interpreted by
  6304.    adding 1900."
  6305.    
  6306.    If you need to specify a year prior to 1000, use leading zeros to
  6307.    ensure it is not misinterpreted as a "non-Y2K-compliant" modern year:
  6308.    
  6309.   7-Oct-77                                 (19771007 00:00:00)
  6310.   7-Oct-0077                               (00771007 00:00:00)
  6311.  
  6312.     8.13.2. The Time
  6313.     
  6314.    The basic time format is hh:mm:dd; that is hours, minutes, seconds,
  6315.    separated by colons, perhaps with an optional fractional second
  6316.    separated by a decimal point (period). The hours are in 24-hour
  6317.    format; 12 is noon, 13 is 1pm, and so on. Fields omitted from the
  6318.    right default to zero. Fields can be omitted from the left or middle
  6319.    by including the field's terminating colon. Examples:
  6320.    
  6321.   11:59:59                                 (11:59:59 AM)
  6322.   11:59                                    (11:59:00 AM)
  6323.   11                                       (11:00:00 AM)
  6324.   11:59:59.33                              (11:59:59 AM)
  6325.   11:59:59.66                              (Noon)
  6326.   03:21:00                                 (3:21:00 AM)
  6327.   3:21:00                                  (3:21:00 AM)
  6328.   15:21:00                                 (3:21:00 PM)
  6329.   :21:00                                   (00:21:00 AM)
  6330.   ::01                                     (00:00:01 AM)
  6331.   11::59                                   (11:00:59 AM)
  6332.  
  6333.    Leading zeros can be omitted, but it is customary and more readable to
  6334.    keep them in the minute and second fields:
  6335.    
  6336.   03:02:01                                 (03:02:01 AM)
  6337.   3:02:01                                  (03:02:01 AM)
  6338.   3:2:1                                    (03:02:01 AM)
  6339.  
  6340.    AM/PM notation is accepted if you wish to use it:
  6341.    
  6342.   11:59:59                                 (11:59:59 AM)
  6343.   11:59:59AM                               (11:59:59 AM)
  6344.   11:59:59A.M.                             (11:59:59 AM)
  6345.   11:59:59am                               (11:59:59 AM)
  6346.   11:59:59a.m.                             (11:59:59 AM)
  6347.   11:59:59PM                               (11:59:59 PM = 23:59:59)
  6348.   11:59:59P.M.                             (11:59:59 PM = 23:59:59)
  6349.   11:59:59pm                               (11:59:59 PM = 23:59:59)
  6350.   11:59:59p.m.                             (11:59:59 PM = 23:59:59)
  6351.  
  6352.    You can omit the colons if you wish, in which case Kermit uses the
  6353.    following rules to interpret the time:
  6354.    
  6355.     1. 6 digits is hh:mm:ss, e.g. 123456 is 12:34:56.
  6356.     2. 5 digits is h:mm:ss, e.g. 12345 is 1:23:45.
  6357.     3. 4 digits is hh:mm, e.g. 1234 is 12:34.
  6358.     4. 3 digits is h:mm, e.g. 123 is 1:23.
  6359.     5. 2 digits is hh, e.g. 12 is 12:00.
  6360.     6. 1 digit is h (the hour), e.g. 1 is 1:00.
  6361.        
  6362.    Examples:
  6363.    
  6364.   1                                        (01:00:00 AM)
  6365.   10                                       (10:00:00 AM)
  6366.   230                                      (02:30:00 AM)
  6367.   230pm                                    (02:30:00 PM = 14:30:00)
  6368.   1115                                     (11:15:00 AM)
  6369.   2315                                     (11:15:00 PM = 23:15:00 PM)
  6370.   23150                                    (02:31:50 AM)
  6371.   231500                                   (23:15:00 PM)
  6372.  
  6373.     8.13.3. Time Zones
  6374.     
  6375.    If a time is given, it can (but need not) be followed by a time zone
  6376.    designator. If no time zone is included, the time is treated as local
  6377.    time and no timezone conversions are performed.
  6378.    
  6379.    The preferred time zone designator is the UTC Offset, as specified in
  6380.    [432]RFC 2822: a plus sign or minus sign immediately followed by
  6381.    exactly four decimal digits, signifying the difference in hh (hours)
  6382.    and mm (minutes) from Universal Coordinated Time (UTC, also known as
  6383.    Greenwich Mean Time, or GMT), with negative numbers to the West and
  6384.    positive numbers to the East. For example:
  6385.    
  6386.   Fri, 13 Jul 2001 12:54:29 -0700
  6387.  
  6388.    indicates a local time of 12:54:29 that is 07 hours and 00 minutes
  6389.    behind (less than, East of) Universal Time. The space is optional, so
  6390.    the example could also be written as:
  6391.    
  6392.   Fri, 13 Jul 2001 12:54:29-0700
  6393.  
  6394.    The following symbolic time zones are also accepted, as specified by
  6395.    [433]RFC 2822 and/or in ISO 8601:
  6396.    
  6397.   GMT  =  +0000       Greenwich Mean Time
  6398.   Z    =  +0000       Zulu (Zero Meridian) Time
  6399.   UTC  =  +0000       Universal Coordinated Time
  6400.   UT   =  +0000       Universal Time
  6401.   EDT  =  -0400       Eastern (USA) Daylight Time
  6402.   EST  =  -0500       Eastern (USA) Standard Time
  6403.   CDT  =  -0500       Central (USA) Daylight Time
  6404.   CST  =  -0600       Central (USA) Standard Time
  6405.   MDT  =  -0600       Mountain (USA) Daylight Time
  6406.   MST  =  -0700       Mountain (USA) Standard Time
  6407.   PDT  =  -0700       Pacific (USA) Daylight Time
  6408.   PST  =  -0800       Pacific (USA) Standard Time
  6409.  
  6410.    Note that GMT, Z, UTC, and UT all express the same concept: standard
  6411.    (not daylight) time at the Zero Meridian. UTC, by the way, is an
  6412.    international standard symbol and does not correspond to the order of
  6413.    the English words, Universal Coordinated Time, but it happens to have
  6414.    the same initial letters as these words. Of course hundreds of other
  6415.    symbolic timezones and variations exist, but they are not
  6416.    standardized, and are therefore not supported by Kermit.
  6417.    
  6418.    When a time zone is included with a time, the time is converted to
  6419.    local time. In case the conversion crosses a midnight boundary, the
  6420.    date is adjusted accordingly. Examples converting to EST (Eastern USA
  6421.    Standard Time = -0500):
  6422.    
  6423.  11:30:00      =  11:30:00
  6424.  11:30:00 EST  =  11:30:00
  6425.  11:30:00 GMT  =  06:30:00
  6426.  11:30:00 PST  =  14:30:00
  6427.  11:30:00Z     =  06:30:00
  6428.  11:30PM GMT   =  18:30:00
  6429.  11:30 -0500   =  11:30:00
  6430.  11:30 -0800   =  08:30:00
  6431.  11:30 +0200   =  04:30:00
  6432.  
  6433.    Unlike most of Kermit's other date-time conversions, timezone
  6434.    knowledge (specifically, the offset of local time from UTC) is
  6435.    embodied in the underlying operating system, not in Kermit itself, and
  6436.    any conversion errors in this department are the fault of the OS. For
  6437.    example, most UNIX platforms do not perform conversions for years
  6438.    prior to 1970.
  6439.    
  6440.     8.13.4. Delta Time
  6441.     
  6442.    Date/time expressions can be composed of a date and/or time and a
  6443.    delta time, or a delta time by itself. When a delta time is given by
  6444.    itself, it is relative to the current local date and time. Delta times
  6445.    have the following general format:
  6446.    
  6447.   {+,-}[number units][hh[:mm[:ss]]]
  6448.  
  6449.    In other words, a delta time always starts with a plus or minus sign,
  6450.    which is followed by a "part1", a "part2", or both. The "part1", if
  6451.    given, specifies a number of days, weeks, months, or years; "part2"
  6452.    specifies a time in hh:mm:ss notation. In arithmetic terms, these
  6453.    represents some number of days or other big time units, and then a
  6454.    fraction of a day expressed as hours, minutes, and seconds; these are
  6455.    to be added to or subtracted from the given (or implied) date and
  6456.    time. The syntax is somewhat flexible, as shown by the following
  6457.    examples:
  6458.    
  6459.   +1 day                (Plus one day)
  6460.   +1day                 (Ditto)
  6461.   +1d                   (Ditto)
  6462.   + 1 day               (Ditto)
  6463.   + 1 day 3:00          (Plus one day and 3 hours)
  6464.   +1d3:00               (Ditto)
  6465.   +1d3                  (Ditto)
  6466.   +3:00:00              (Plus 3 hours)
  6467.   +3:00                 (Ditto)
  6468.   +3                    (Ditto)
  6469.   +2 days               (Plus 2 days)
  6470.   -12 days 7:14:22      (Minus 12 days, 7 hours, 14 minutes, and 22 seconds)
  6471.  
  6472.    The words "week", "month", and "year" can be used like "day" in the
  6473.    examples above. A week is exactly equivalent to 7 days. When months
  6474.    are specified, the numeric month number of the date is incremented or
  6475.    decremented by the given number, and the year and day adjusted
  6476.    accordingly if necessary (for example, 31-Jan-2001 +1month =
  6477.    03-Mar-2001 because February does not have 31 days). When years are
  6478.    specified, they are added or subtracted to the base year. Examples
  6479.    (assuming the current date is 10-Aug-2001 and the current time is
  6480.    19:21:11):
  6481.    
  6482.   18-Sep-2001 +1day              (20010918 00:00:00)
  6483.   today +1day                    (20010811 00:00:00)
  6484.   now+1d                         (20010811 19:21:11)
  6485.   + 1 day                        (20010811 19:21:11)
  6486.   + 1 day 3:14:42                (20010811 22:35:54)
  6487.   + 7 weeks                      (20010928 19:21:11)
  6488.   +1d3:14:42                     (20010811 22:35:54)
  6489.   +1w3:14:42                     (20010817 22:35:54)
  6490.   +1m3:14:42                     (20010910 22:35:54)
  6491.   +1y3:14:42                     (20020810 22:35:54)
  6492.   2 feb 2001 + 10 years          (20110208 00:00:00)
  6493.   2001-02-08 +10y12              (20110208 12:00:00)
  6494.   31-dec-1999 23:59:59+00:00:01  (20000101 00:00:00)
  6495.   28-feb-1996 +1day              (19960229 00:00:00) (leap year)
  6496.   28-feb-1997 +1day              (19970301 00:00:00) (nonleap year)
  6497.   28-feb-1997 +1month            (19970328 00:00:00)
  6498.   28-feb-1997 +1month 11:59:59   (19970328 11:59:59)
  6499.   28-feb-1997 +20years           (20170228 00:00:00)
  6500.   28-feb-1997 +8000years         (99970228 00:00:00)
  6501.  
  6502.    For compatibility with VMS, the following special delta-time format is
  6503.    also accepted:
  6504.    
  6505.   +number-hh:mm:ss
  6506.   -number-hh:mm:ss
  6507.  
  6508.    (no spaces). The hyphen after the number indicates days. It
  6509.    corresponds exactly to the Kermit notation:
  6510.    
  6511.   +numberdhh:mm:ss
  6512.   -numberdhh:mm:ss
  6513.  
  6514.    The following forms all indicate exactly the same date and time:
  6515.    
  6516.   18-Sep-2001 12:34:56 +1-3:23:01
  6517.   18-Sep-2001 12:34:56 +1d3:23:01
  6518.   18-Sep-2001 12:34:56 +1 day 3:23:01
  6519.  
  6520.    and mean "add a day plus 3 hours, 23 minutes, and 1 second" to the
  6521.    given date.
  6522.    
  6523.    Note that delta times are not at all the same as UTC offsets; the
  6524.    former specifies an adjustment to the given date/time and the latter
  6525.    specifies that the local time is a particular distance from Universal
  6526.    Time, for example:
  6527.    
  6528.   11-Aug-2001 12:34:56 -0800          (20010811 16:34:56 -- UTC Offset)
  6529.   11-Aug-2001 12:34:56 -08:00         (20010811 04:34:56 -- Delta time)
  6530.  
  6531.    If you give a time followed by a modifer that starts with a + or -
  6532.    sign, how does Kermit know whether it's a UTC offset or a delta time?
  6533.    It is treated as a UTC offset if the sign is followed by exactly four
  6534.    decimal digits; otherwise it is a delta time. Examples (for USA
  6535.    Eastern Daylight Time):
  6536.    
  6537.   11-Aug-2001 12:34:56 -0800          (20010811 16:34:56 -- UTC Offset)
  6538.   11-Aug-2001 12:34:56 -08:00         (20010811 04:34:56 -- Delta time)
  6539.   11-Aug-2001 12:34:56 -800           (20010811 04:34:56 -- Delta time)
  6540.   11-Aug-2001 12:34:56 -8             (20010811 04:34:56 -- Delta time)
  6541.  
  6542.    The first example says that at some unknown place which is 8 hours
  6543.    ahead of Universal Time, the time is 12:34:56, and this corresponds to
  6544.    16:34:56 in Eastern Daylight time. The second example says to subtract
  6545.    8 hours from the local time. The third and fourth are delta times
  6546.    because, even though a colon is not included, the time does not
  6547.    consist of exactly 4 digits.
  6548.    
  6549.    When a delta time is written after a timezone, however, there is no
  6550.    ambiguity and no syntax distinction is required:
  6551.    
  6552.   11-Aug-2001 12:34:56 -0800 -0800    (20010811 08:34:56)
  6553.   11-Aug-2001 12:34:56 -0800 -08:00   (Ditto)
  6554.   11-Aug-2001 12:34:56 -08:00 -08:00  (Illegal)
  6555.  
  6556.     8.13.5. The DATE Command
  6557.     
  6558.    Obviously a great many combinations of date, time, time zone, and
  6559.    delta time are possible, as well as many formatting options. The
  6560.    purpose of all this flexibility is to comply with as many standards as
  6561.    possible -- Internet RFCs, ISO standards, and proven corporate
  6562.    standards -- as well as with notations commonly used by real people,
  6563.    in order that dates and times from the widest variety of sources can
  6564.    be assigned to a variable and used in any date-time field in any
  6565.    Kermit command.
  6566.    
  6567.    You can test any date-and/or-time format with the DATE command, which
  6568.    converts it to standard yyyymmdd hh:mm:ss format if it is understood,
  6569.    or else gives an explicit error message (rather than just "BAD DATE"
  6570.    as in previous C-Kermit releases) to indicate what is wrong with it.
  6571.    Examples (on Tuesday, 31 July 2001 in New York City, Eastern Daylight
  6572.    Time, UTC -0400):
  6573.    
  6574.   DATE command argument                   Result           
  6575.   12:30                                   20010731 12:30:00
  6576.   12:30:01                                20010731 12:30:01
  6577.   12:30:01.5                              20010731 12:30:02
  6578.   1230                                    20010731 12:30:00
  6579.   230                                     20010731 02:30:00
  6580.   230+1d                                  20010801 02:30:00
  6581.   230+1d3:00                              20010801 05:30:00
  6582.   20010718 19:21:15                       20010718 19:21:15
  6583.   20010718_192115                         20010718 19:21:15
  6584.   20010718T192115                         20010718 19:21:15
  6585.   18 Jul 2001 +0400                       20010717 23:59:59
  6586.   18 Jul 2001 192115                      20010718 19:21:15
  6587.   18 Jul 2001 192115.8                    20010718 19:21:16
  6588.   18-Jul-2001T1921                        20010718 19:21:00
  6589.   18-Jul-2001 1921Z                       20010718 15:21:00
  6590.   18-Jul-2001 1921 GMT                    20010718 15:21:00
  6591.   18-Jul-2001 1921 UTC                    20010718 15:21:00
  6592.   18-Jul-2001 1921 Z                      20010718 15:21:00
  6593.   18-Jul-2001 1921Z                       20010718 15:21:00
  6594.   18-Jul-2001 1921 -04:00:00              20010718 19:21:00
  6595.   21-Jul-2001_08:20:00am                  20010721 08:20:00
  6596.   21-Jul-2001_8:20:00P.M.                 20010721 20:20:00
  6597.   Fri Jul 20 11:26:25 2001                20010720 11:26:25
  6598.   Fri Jul 20 11:26:25 GMT 2001            20010720 07:26:25
  6599.   Sun, 9 Apr 2000 06:46:46 +0100          20000409 01:46:46
  6600.   Sunday, 9 Apr 2000 06:46:46 +0100       20000409 01:46:46
  6601.   now                                     20010731 19:41:12
  6602.   today                                   20010731 00:00:00
  6603.   today 09:00                             20010731 09:00:00
  6604.   tomorrow                                20010801 00:00:00
  6605.   tomorrow 09:00                          20010801 09:00:00
  6606.   tomorrow 09:00 GMT                      20010801 05:00:00
  6607.   yesterday                               20010730 00:00:00
  6608.   yesterday 09:00                         20010730 09:00:00
  6609.   + 3 days                                20010803 00:00:00
  6610.   +3 days                                 20010803 00:00:00
  6611.   +3days                                  20010803 00:00:00
  6612.   + 3days                                 20010803 00:00:00
  6613.   + 3 days 09:00                          20010803 09:00:00
  6614.   + 2 weeks                               20010814 00:00:00
  6615.   + 1 month                               20010831 00:00:00
  6616.   - 7 months                              20001231 00:00:00
  6617.   + 10 years                              20110731 00:00:00
  6618.   friday                                  20010803 00:00:00
  6619.   saturday                                20010804 00:00:00
  6620.   sunday                                  20010805 00:00:00
  6621.   monday                                  20010806 00:00:00
  6622.   tuesday                                 20010731 00:00:00
  6623.   wednesday                               20010801 00:00:00
  6624.   thursday                                20010802 00:00:00
  6625.   friday 07:00                            20010803 07:00:00
  6626.   thursday 1:00pm                         20010802 13:00:00
  6627.   thursday 1:00pm GMT                     20010802 09:00:00
  6628.   Thu, 10 Nov 94 10:50:47 EST             19941110 10:50:47
  6629.   Fri, 20 Oct 1995 18:35:15 -0400 (EDT)   19951020 18:35:15
  6630.   31/12/2001                              20011231 00:00:00
  6631.   12/31/2001                              20011231 00:00:00
  6632.   2001-July-20                            20010720 00:00:00
  6633.   2001-September-30                       20010930 00:00:00
  6634.   30-September-2001                       20010930 00:00:00
  6635.   Sep 30, 2001 12:34:56                   20010930 12:34:56
  6636.   September 30, 2001                      20010930 00:00:00
  6637.   September 30, 2001 630                  20010930 06:30:00
  6638.   September 30 2001 630                   20010930 06:30:00
  6639.   Sep-30-2001 12:34:59                    20010930 12:34:59
  6640.   20010807113542.014                      20010807 11:35.42
  6641.   20010807113542.014Z                     20010807 07:35:42
  6642.  
  6643.     8.13.6. New Date-Time Functions
  6644.     
  6645.    In the following descriptions, date-time function arguments are the
  6646.    same free-format date-time strings discussed above, with the same
  6647.    defaults for missing fields. They are automatically converted to
  6648.    standard format internally prior to processing.
  6649.    
  6650.    \fcvtdate(d1)
  6651.           Converts the date-time d1 to standard format and local time.
  6652.           This function is not new, but now it accepts a wider range of
  6653.           argument formats that can include timezones and/or delta times.
  6654.           
  6655.    \futcdate(d1)
  6656.           Converts the date-time d1 to Universal Coordinated Time (UTC),
  6657.           also known as GMT or Zulu or Zero-Meridian time. The default d1
  6658.           is NOW. If d1 is a valid date-time, the UTC result is returned
  6659.           in standard format, yyyymmdd hh:ss:mm.
  6660.           
  6661.    \fcmpdates(d1,d2)
  6662.           Compares two free-format date-times, d1 and d2, and, if both
  6663.           arguments are valid, returns a number: -1 if d1 is earlier than
  6664.           (before) d2; 0 if d1 is the same as d2; 1 if d1 is later than
  6665.           (after) d2.
  6666.           
  6667.    \fdiffdates(d1,d2)
  6668.           Computes the difference between two free-format date-times, d1
  6669.           and d2. If both arguments are valid, returns a delta time which
  6670.           is negative if d1 is earlier than (before) d2 and positive
  6671.           otherwise. If d1 and d2 are equal, the result is "+0:00".
  6672.           Otherwise, the result consists of the number of days, hours,
  6673.           minutes, and seconds that separate the two date-times. If the
  6674.           number of days is zero, it is omitted. If the number of days is
  6675.           nonzero but the hours, minutes, and seconds are all zero, the
  6676.           time is omitted. if the seconds are zero, they are omitted.
  6677.           
  6678.    \fdelta2secs(dt)
  6679.           Converts a delta time to seconds. For example, "+1d00:00:01" to
  6680.           86401. Valid delta times must start with a + or - sign. Days
  6681.           are accepted as time units, but not years, months, or weeks. If
  6682.           the result would overflow a computer long word (as would happen
  6683.           with 32-bit long words when the number of days is greater than
  6684.           24854), the function fails.
  6685.           
  6686.    HINT: Although Kermit has a number of built-in date and time
  6687.    variables, it doesn't have a single one suitable for writing a
  6688.    timestamp. For this you would normally use something like "\v(ndate)
  6689.    \v(time)". But \fcvtdate() (with no arguments) is equivalent: it
  6690.    returns the current date and time in yyyymmdd hh:mm:ss format,
  6691.    suitable for time stamping.
  6692.    
  6693.     8.13.7. Date-Time Programming Examples
  6694.     
  6695.    Here's a macro that converts any date-time to UTC, which you might use
  6696.    if C-Kermit didn't already have a \futcdate() function:
  6697.    
  6698.   define utcdate {
  6699.       .local := \fcvtdate(\%*)                 ; 1.
  6700.       .tmp := \fcvtdate(\m(local)UTC)          ; 2.
  6701.       .offset := \fdiffdate(\m(local),\m(tmp)) ; 3.
  6702.       .utc := \fcvtdate(\m(local)\m(offset))   ; 4.
  6703.       sho mac utc                              ; 5.
  6704.   }
  6705.  
  6706.    Brief explanation: Line 1 converts the macro argument, a free-format
  6707.    date-time, to standard-format local time. Line 2 appends the "UTC"
  6708.    timezone to the local time and converts the result to local time. In
  6709.    other words, we take the same time as the local time, but pretend it's
  6710.    UTC time, and convert it to local time. For example, if New York time
  6711.    is 4 hours ahead of UTC, then 6:00pm New York time is 2:00pm UTC. Line
  6712.    3 gets the difference of the two results (e.g. "+04:00"). Line 4
  6713.    appends the difference (delta time) to the local time, and converts it
  6714.    again, whic adds (or subtracts) the UTC offset to the given time. Line
  6715.    5 displays the result.
  6716.    
  6717.    Here's a script that opens a web page, gets its headers into an array,
  6718.    scans the array for the "Last-Modified:" header, and inteprets it:
  6719.  
  6720.   http open www.columbia.edu
  6721.   if fail stop 1 HTTP OPEN failed
  6722.   http /array:a head index.html /dev/null
  6723.   if fail stop 1 HTTP GET failed
  6724.   show array a
  6725.   for \%i 1 \fdim(&a) 1 {
  6726.       .\%x := \findex(:,\&a[\%i])
  6727.       if not \%x continue
  6728.       .tag := \fleft(\&a[\%i],\%x-1)
  6729.       .val := \fltrim(\fsubstr(\&a[\%i],\%x+1))
  6730.       if ( eq "\m(tag)" "Last-Modified" ) {
  6731.           echo HTTP Date: \m(val)
  6732.           .rdate := \fcvtdate(\m(val))
  6733.           echo {Standard Date (local): \m(rdate)}
  6734.           echo {Standard Date (UTC):   \futcdate(\m(rdate))}
  6735.           break
  6736.       }
  6737.   }
  6738.   http close
  6739.  
  6740.    The result:
  6741.    
  6742.   HTTP Date: Mon, 13 Aug 2001 20:05:42 GMT
  6743.   Standard Date (local): 20010813 16:05:42
  6744.   Standard Date (UTC):   20010813 20:05:42
  6745.  
  6746.    As you can see, Kermit had no trouble decoding the date-time-string
  6747.    from the website, converting to local time, and converting back to UTC
  6748.    with no conflicts or loss of information. If it had been in any other
  6749.    known format, the result would have been the same.
  6750.    
  6751.    Now suppose we want to download the web page only if it is newer than
  6752.    our local copy. The \fdate(filename) function (which returns the
  6753.    modification date-time of the given file) and the new \fcmpdates()
  6754.    function make it easy. Insert the following just before the BREAK
  6755.    statement:
  6756.    
  6757.   if ( < 0 \fcmpdates(\m(rdate),\fdate(index.html)) ) {
  6758.      echo GETTING index.html...
  6759.      http get index.html index.html
  6760.      if success echo HTTP GET OK
  6761.   } else {
  6762.      echo index.html: no update needed
  6763.   }
  6764.   http close
  6765.   exit
  6766.  
  6767.    This says, "if 0 is less than the comparison of the remote file date
  6768.    and the local file date, get the remote file, otherwise skip it." And
  6769.    it automatically reconciles the time-zone difference (if any).
  6770.    
  6771.    It would be nice to be able to extend this script into a
  6772.    general-purpose website updater, but unfortunately HTTP protocol
  6773.    doesn't provide any mechanism for the client to ask the server for a
  6774.    list of files, recursive or otherwise.
  6775.    
  6776.    [ [434]Top ] [ [435]Contents ] [ [436]C-Kermit Home ] [ [437]Kermit
  6777.    Home ]
  6778.      _________________________________________________________________
  6779.    
  6780.   8.14. Trapping Keyboard Interruption
  6781.   
  6782.    Normally when you type Ctrl-C and Kermit is in command mode (as
  6783.    opposed to CONNECT mode) with COMMAND INTERRUPTION ON (as it is unless
  6784.    you have set it OFF), Kermit interrupts any command that is currently
  6785.    in progress, and if a command file or macro is executing, rolls the
  6786.    command stack back to top level, closing all open command files,
  6787.    deactivating all macros, deallocating all local variables and arrays,
  6788.    and leaving you at the command prompt.
  6789.    
  6790.    Suppose, however, you want certain actions to occur when a script is
  6791.    interrupted; for example, closing open files, writing log entries, or
  6792.    displaying summary results. You can do this by defining a macro named
  6793.    ON_CTRLC. When Ctrl-C is detected, and a macro with this name is
  6794.    defined, Kermit executes it from the current command level, thus
  6795.    giving it full access to the environment in which the interruption
  6796.    occurred, including local variables and open files. Only when the
  6797.    ON_CTRLC macro completes execution is the command stack rolled back to
  6798.    top level.
  6799.    
  6800.    Once the ON_CTRLC macro is defined, it can be executed only once. This
  6801.    is to prevent recursion if the user types Ctrl-C while the ON_CTRLC
  6802.    macro is executing. If you type Ctrl-C while the Ctrl-C macro is
  6803.    active, this does not start a new copy of ON_CTRLC; rather, it returns
  6804.    to the top-level command prompt. After the ON_CTRLC macro returns, it
  6805.    has been removed from the macro table so if you want to use it again
  6806.    or install a different Ctrl-C trap, you must execute a new DEFINE
  6807.    ON_CTRLC command. In any case, as always when you interrupt a script
  6808.    with Ctrl-C, its completion status is FAILURE.
  6809.    
  6810.    Normally the ON_CTRLC macro would be defined in the command file or
  6811.    macro to which it applies, and should be declared LOCAL. This way, if
  6812.    the command file or macro completes successfully without being
  6813.    interrupted, the ON_CTRLC definition disappears automatically.
  6814.    Otherwise the definition would still be valid and the macro would be
  6815.    executed, probably out of context, the next time you typed Ctrl-C.
  6816.    
  6817.    Here's a simple example of a command file that sets a Ctrl-C trap for
  6818.    itself:
  6819.    
  6820.   local on_ctrlc              ; Make Ctrl-C trap local to this command file.
  6821.   define on_ctrlc {           ; Define the ON_CTRLC macro.
  6822.       echo Interrupted at \v(time).
  6823.       echo Iterations: \%n
  6824.   }
  6825.   xecho Type Ctrl-C to quit
  6826.   for \%n 1 999 1 {           ; Prints a dot every second until interrupted.
  6827.       sleep 1
  6828.       xecho .
  6829.   }
  6830.   echo Finished normally at \v(time) ; Get here only if not interrupted.
  6831.   decrement \%n
  6832.   echo Iterations: \%n
  6833.  
  6834.    This prints a summary no matter whether it completes normally or is
  6835.    interrupted from the keyboard. In both cases the trap is automatically
  6836.    removed afterwards.
  6837.    
  6838.    For an example of how to use ON_CTRLC to debug scripts, see
  6839.    [438]Section 8.1.
  6840.    
  6841.    [ [439]Top ] [ [440]Contents ] [ [441]C-Kermit Home ] [ [442]Kermit
  6842.    Home ]
  6843.   __________________________________________________________________________
  6844.  
  6845. 9. S-EXPRESSIONS
  6846.  
  6847.    This section is primarily for those who want to write
  6848.    calculation-intensive scripts, especially if they require
  6849.    floating-point arithmetic, and/or for those who are familiar with the
  6850.    LISP programming language.
  6851.    
  6852.    Ever since C-Kermit version 5 was released in 1988, scripting has been
  6853.    one of its major attractions, and arithmetic is key part of it.
  6854.    Versions 5 and 6 included integer arithmetic only, using traditional
  6855.    algebraic notation, e.g.:
  6856.    
  6857.   echo \fevaluate(3*(2+7)/2)
  6858.   13
  6859.  
  6860.    C-Kermit 7.0 added support for floating-point arithmetic, but only
  6861.    through function calls:
  6862.    
  6863.   echo \fppdivide(\ffpmultiply(3.0,\fpadd(2.0,7.0)),2.0)
  6864.   13.5
  6865.  
  6866.    C-Kermit 8.0 introduces a third form of arithmetic that treats
  6867.    integers and floating-point numbers uniformly, is easier to read and
  6868.    write, and executes very quickly:
  6869.    
  6870.   (/ (* 3 (+ 2 7)) 2)
  6871.   13.5
  6872.  
  6873.    But first some background.
  6874.    
  6875.    The Kermit command and scripting language differs from true
  6876.    programming languages (such as C or Fortran) in many ways; one of the
  6877.    most prominent differences is the way in which variables are
  6878.    distinguished from constants. In a command language, words are taken
  6879.    literally; for example, the Unix shell:
  6880.    
  6881.   cat foo.bar
  6882.  
  6883.    displays the file named foo.bar. Whereas in a programming language
  6884.    like C, words are assumed to be variables:
  6885.    
  6886.   s = foo.bar;    /* Assigns the value of foo.bar to the variable s */
  6887.  
  6888.    To make a programming language take words literally, you have to quote
  6889.    or "escape" them:
  6890.    
  6891.   s = "foo.bar";  /* Assigns a pointer to the string "foo.bar" to the variable
  6892. s */
  6893.  
  6894.    The opposite holds for command languages: to get them to treat a word
  6895.    as a variable rather than a constant, you have to escape them. For
  6896.    example, in the Unix shell:
  6897.    
  6898.   foo=123         ; Assign value 123 to variable foo.
  6899.   echo foo        ; Prints "foo"
  6900.   echo $foo       ; Prints "123"
  6901.  
  6902.    And in Kermit:
  6903.    
  6904.   define foo 123  ; Assign value 123 to variable foo.
  6905.   echo 123        ; This prints "123".
  6906.   echo foo        ; This prints "foo".
  6907.   echo \m(foo)    ; This prints "123".
  6908.  
  6909.    In other words, character strings (such as "foo" above) are
  6910.    interpreted as literal strings, rather than variable names, except in
  6911.    special commands like DEFINE that deal specifically with variable
  6912.    names (or in numeric contexts as explained in [443]Section 8.2). The
  6913.    special "escape" character (dollar sign ($) for the shell, backslash
  6914.    (\) for Kermit) indicates that a variable is to be replaced by its
  6915.    value.
  6916.    
  6917.    The requirement to escape variable names in command languages normally
  6918.    does not impose any special hardship, but can add a considerable
  6919.    notational burden to arithmetic expressions, which are typically full
  6920.    of variables. Especially in Kermit when floating point numbers are
  6921.    involved, where you must use special \ffpxxx() functions, e.g.
  6922.    "\fpadd(\m(a),\m(b))" rather than the simple "+" operator to add two
  6923.    floating-point numbers together, because the original arithmetic
  6924.    handler doesn't support floating point (this might change in the
  6925.    future). To illustrate, the general formula for the area of a triangle
  6926.    is:
  6927.    
  6928.   sqrt(s * (s - a) * (s - b) * (s - c))
  6929.  
  6930.    where a, b, and c are the lengths of the triangle's three sides and:
  6931.    
  6932.   s = (a + b + c) / 2
  6933.  
  6934.    Except in special cases (e.g. a = 3, b = 4, c = 5), the result has a
  6935.    fractional part so the computation must be done using floating-point
  6936.    arithmetic. We can create a Kermit 7.0 function for this as follows:
  6937.    
  6938.   def area {
  6939.       local s t1 t2 t3
  6940.       assign s \ffpdiv(\ffpadd(\ffpadd(\%1,\%2),\%3),2.0)
  6941.       assign t1 \ffpsub(\m(s),\%1)
  6942.       assign t2 \ffpsub(\m(s),\%2)
  6943.       assign t3 \ffpsub(\m(s),\%3)
  6944.       return \ffpsqrt(\ffpmul(\m(s),\ffpmul(\m(t1),\ffpmul(\m(t2),\m(t3)))))
  6945.   }
  6946.  
  6947.    But as you can see, this is rather cumbersome. Note, in particular,
  6948.    that arithmetic functions like \ffpadd(), \ffpmul(), etc, take exactly
  6949.    two operands (like their symbolic counterparts + and *), so obtaining
  6950.    the product of three or more numbers (as we do in this case) is
  6951.    awkward.
  6952.    
  6953.    Using the alternative S-Expression notation, we can reduce this to a
  6954.    form that is both easier to read and executes faster (the details are
  6955.    explained later):
  6956.    
  6957.   def newarea {
  6958.       (let s (/ (+ \%1 \%2 \%3) 2.0))
  6959.       (sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  6960.   }
  6961.  
  6962.    In both examples, the \%1..3 variables are the normal Kermit macro
  6963.    arguments, referenced by the normal escaping mechanism. For increased
  6964.    readability, we can also assign the macro arguments \%1, \%2, and \%3
  6965.    to the letters a, b, and c corresponding to our formula:
  6966.    
  6967. def newarea {
  6968.     (let a \%1 b \%2 c \%3)
  6969.     (let s (/ (+ a b c) 2.0))
  6970.     (sqrt (* s (- s a) (- s b) (- s c)))
  6971. }
  6972.  
  6973.    And now the Kermit function reads almost like the original formula.
  6974.    Here Kermit behaves more like a regular programming language. In an
  6975.    S-Expression, macro names need not be escaped when they are used as
  6976.    the names of numeric variables.
  6977.    
  6978.    [ [444]Top ] [ [445]Contents ] [ [446]C-Kermit Home ] [ [447]Kermit
  6979.    Home ]
  6980.      _________________________________________________________________
  6981.    
  6982.   9.1. What is an S-Expression?
  6983.   
  6984.    The S-Expression concept is borrowed from the Lisp programming
  6985.    language. "S-Expression" is short for Symbolic Expression (itself
  6986.    sometimes shortened to SEXP). S-Expressions provide a kind of
  6987.    Alternative Mini-Universe within the Kermit command language when the
  6988.    regular rules don't apply, a universe enclosed in parentheses.
  6989.    
  6990.    C-Kermit does not pretend to be a full Lisp interpreter; only the
  6991.    arithmetic parts of Lisp have been incorporated: S-Expressions that
  6992.    operate on numbers and return numeric values (plus extensibility
  6993.    features described in [448]Section 9.8, which allow some degree of
  6994.    string processing).
  6995.    
  6996.    An S-Expression is a list of zero or more items, separated by spaces,
  6997.    within parentheses. Examples:
  6998.    
  6999.   ()
  7000.   (1)
  7001.   (a)
  7002.   (+ a 1)
  7003.   (* 2 a b)
  7004.  
  7005.    If the S-Expression is empty, it has the NIL (empty) value. If it is
  7006.    not empty and the first item is an operator (such as + or *), there
  7007.    can be zero or more subsequent items, called the operands:
  7008.    
  7009.   (+ 1 2)
  7010.  
  7011.    Here the operator is "+" and the operands are "1" and "2", and the
  7012.    value of the S-Expression is the value of the operation (in this case
  7013.    3). The operator always comes first, which is different from the
  7014.    familiar algebraic notation; this because S-Expression operators can
  7015.    allow different numbers of operands:
  7016.    
  7017.   (+ 1)
  7018.   (+ 1 2)
  7019.   (+ 1 2 3 4 5 6 7 8 9)
  7020.  
  7021.    If the first item in the S-Expression is not an operator, then it must
  7022.    be a variable or a number (or a macro; see [449]Section 9.8), and the
  7023.    S-Expression can only contain one item; in this case, the
  7024.    S-Expression's value is the value of the variable or number:
  7025.    
  7026.   (a)
  7027.   (3)
  7028.  
  7029.    Operands can be numbers, variables that have numeric values, functions
  7030.    that return numbers, or other S-Expressions. To illustrate an
  7031.    S-Expression within an S-Expression, observe that:
  7032.    
  7033.   (+ 1 2)
  7034.  
  7035.    is equivalent to any of the following (plus an infinite number of
  7036.    others):
  7037.    
  7038.   (+ 1 (+ 1 1))
  7039.   (+ (- 3 2) (/ 14 (+ 3 4)))
  7040.  
  7041.    S-Expressions can be nested to any reasonable level; for example, the
  7042.    value of the following S-Expression is 64:
  7043.    
  7044.   (- (* (+ 2 (* 3 4)) (- 9 (* 2 2))) 6)
  7045.  
  7046.    Operators have no precedence, implied or otherwise, since they can't
  7047.    be mixed. The only exceptions are unary + and -, which simply indicate
  7048.    the sign of a number:
  7049.    
  7050.   (* 3 -1)
  7051.  
  7052.    Order of evaluation is specified entirely by parentheses, which are
  7053.    required around each operator and its operands: (+ a (* b c)) instead
  7054.    of (a + b * c).
  7055.    
  7056.    S-Expressions provide a simple and isolated environment in which
  7057.    Kermit's macro names can be used without the \m(...) escaping that is
  7058.    normally required. Given:
  7059.    
  7060.   define a 1
  7061.   define b 2
  7062.   define c 3
  7063.  
  7064.    Then:
  7065.    
  7066.   (+ \m(a) \m(b) \m(c))
  7067.  
  7068.    is equivalent to:
  7069.    
  7070.   (+ a b c)
  7071.  
  7072.    Within an S-Expression, as in other strictly numeric contexts
  7073.    ([450]Section 8.2), any operand that starts with a letter is treated
  7074.    as a Kermit macro name. In this context, abbreviations are not
  7075.    accepted; variable names must be spelled out in full. Alphabetic case
  7076.    is not significant; "a" and "A" are the same variable, but both are
  7077.    different from "area".
  7078.    
  7079.    Of course, regular Kermit variables and functions can be used in
  7080.    S-Expressions in the normal ways:
  7081.    
  7082.   (* \v(math_pi) (^ \%r 2))             ; Area of a circle with radius \%r
  7083.   (+ \fjoin(&a))                        ; Sum of all elements of array \&a[]
  7084.  
  7085.    [ [451]Top ] [ [452]Contents ] [ [453]C-Kermit Home ] [ [454]Kermit
  7086.    Home ]
  7087.      _________________________________________________________________
  7088.    
  7089.   9.2. Integer and Floating-Point-Arithmetic
  7090.   
  7091.    Normally, if all numbers in an S-Expression are integers, the result
  7092.    is an integer:
  7093.    
  7094.   (+ 1 1)                               ; Result is 2
  7095.   (/ 9 3)                               ; Result is 3
  7096.  
  7097.    If any of the operands is floating point, however, the result is also
  7098.    floating point:
  7099.    
  7100.   (+ 1 1.0)                             ; Result is 2.0
  7101.   (/ 9.0 3)                             ; Result is 3.0
  7102.  
  7103.    If all the operands are integers but the result has a fractional part,
  7104.    the result is floating point:
  7105.    
  7106.   (/ 10 3)                              ; Result is 3.333333333333333
  7107.  
  7108.    To force an integer result in such cases, use the TRUNCATE operator:
  7109.    
  7110.   (truncate (/ 10 3))                   ; Result is 3
  7111.  
  7112.    Similarly, to force a computation to occur in floating point, you can
  7113.    coerce one of its operands to FLOAT:
  7114.    
  7115.   (+ 1 (float 1))                       ; Result is 1.0
  7116.  
  7117.    The result is also floating point if the magnitude of any integer
  7118.    operand, intermediate result, or the result itself, is larger than the
  7119.    maximum for the underlying machine architecture:
  7120.    
  7121.   (^ 100 100)
  7122.  
  7123.    If the result is too large even for floating-point representation,
  7124.    "Infinity" is printed; if it is too small to be distinguished from 0,
  7125.    0.0 is returned.
  7126.    
  7127.    Large numbers can be used and large results generated, but they are
  7128.    accurate only to the precision of the underlying machine. For example,
  7129.    the result of:
  7130.    
  7131.  (+ 111111111111111111111 222222222222222222222)
  7132.  
  7133.    should be 333333333333333333333, but 333333333333333300000.0 is
  7134.    produced instead if the machine is accurate to only about 16 decimal
  7135.    digits, even with coercion to floating-point. The order of magnitude
  7136.    is correct but the least significant digits are wrong. The imprecise
  7137.    nature of the result is indicated by the ".0" at the end. Contrast
  7138.    with:
  7139.    
  7140.  (+ 111111111 222222222)
  7141.  
  7142.    which produces an exact integer result.
  7143.    
  7144.    [ [455]Top ] [ [456]Contents ] [ [457]C-Kermit Home ] [ [458]Kermit
  7145.    Home ]
  7146.      _________________________________________________________________
  7147.    
  7148.   9.3. How to Use S-Expressions
  7149.   
  7150.    S-Expressions may be given as commands to C-Kermit. Any command whose
  7151.    first character is "(" (left parenthesis) is interpreted as an
  7152.    S-Expression.
  7153.    
  7154.    If you enter an S-Expression at the C-Kermit> prompt, its result is
  7155.    printed:
  7156.    
  7157.   C-Kermit>(/ 10.0 3)
  7158.    3.333333333333333
  7159.   C-Kermit>
  7160.  
  7161.    If an S-Expression is executed within a macro or command file, its
  7162.    value is not printed. However, you can control the printing action
  7163.    with:
  7164.    
  7165.    SET SEXPRESSION ECHO { AUTO, ON, OFF }
  7166.           AUTO is the default, meaning print the value at top level only;
  7167.           ON means always print the value; OFF means never print it.
  7168.           
  7169.    In any case, the value of the most recent S-Expression (and the
  7170.    S-Expression itself) may be accessed programmatically through the
  7171.    following variables:
  7172.    
  7173.    \v(sexpression)
  7174.           The S-Expression most recently executed.
  7175.           
  7176.    \v(svalue)
  7177.           The value of the S-Expression most recently executed.
  7178.           
  7179.    Besides issuing S-Expressions as commands in themselves, you can also
  7180.    execute them anywhere within a Kermit command, but in this case they
  7181.    must be enclosed in a function call (otherwise they are taken
  7182.    literally):
  7183.    
  7184.    \fsexpression(s)
  7185.           The argument "s" is an S-Expression; the outer parentheses may
  7186.           be omitted. The value of the S-Expression is returned. Note
  7187.           that since S-Expressions usually contain spaces, some form of
  7188.           grouping or quoting might be needed in some contexts:
  7189.           
  7190.   echo \fsexpression((+ 1 1))            ; Outer parentheses may be included
  7191.   echo \fsexpr(+ 1 1)                    ; Outer parentheses may be omitted
  7192.   echo Value = "\fsexp(+ 1 a)"           ; Can be embedded in strings
  7193.   echo Value = \&a[\fsexp(/ b 2)]        ; Can be used in array subscripts
  7194.   if = {\fsexp(+ 1 1)} 2 {               ; Braces needed here for grouping
  7195.       echo One plus one still equals two
  7196.   }
  7197.  
  7198.    The IF statement illustrates how to use S-Expressions as (or in) IF or
  7199.    WHILE conditions:
  7200.    
  7201.      * Although S-Expressions and IF conditions are similar in
  7202.        appearance, they are not interchangeable. Therefore you must use
  7203.        \fsexpr() to let Kermit know it's an S-Expression rather than a
  7204.        regular IF condition, or a boolean or algebraic expression within
  7205.        an IF condition.
  7206.      * In contexts where a single "word" is expected, you must enclose
  7207.        the \fsexp() invocation in braces if the S-Expression contains
  7208.        spaces (and most of the do).
  7209.        
  7210.    If an S-Expression is the last command executed in a macro, its value
  7211.    becomes the return value of the macro; no RETURN command is needed.
  7212.    Example:
  7213.    
  7214.   def newarea {
  7215.       (let s (/ (+ \%1 \%2 \%3) 2.0))
  7216.       (sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  7217.   }
  7218.  
  7219.    This is equivalent to (but more efficient than):
  7220.    
  7221.   def newarea {
  7222.       (let s (/ (+ \%1 \%2 \%3) 2.0))
  7223.       return \fsexp(sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  7224.   }
  7225.  
  7226.    When an S-Expression is entered as a command -- that is, the first
  7227.    nonblank character of the command is a left parenthesis -- then it is
  7228.    allowed to span multiple lines, as many as you like, until the first
  7229.    left parenthesis is matched:
  7230.    
  7231.   (let s (/
  7232.           (+
  7233.            \%1
  7234.            \%2
  7235.            \%3
  7236.            )
  7237.           2.0
  7238.           )
  7239.        )
  7240.   (sqrt (*
  7241.          s
  7242.          (- s \%1)
  7243.          (- s \%2)
  7244.          (- s \%3)
  7245.          )
  7246.         )
  7247.  
  7248.    The S-Expression concept lends itself easily to embedding and
  7249.    recursion, but the depth to which recursion can occur is limited by
  7250.    the resources of the computer (memory size, address space, swap space
  7251.    on disk) and other factors. There is no way that C-Kermit can know
  7252.    what this limit is, since it varies not only from computer to
  7253.    computer, but also from moment to moment. If resources are exhausted
  7254.    by recursion, C-Kermit simply crashes; there's no way to trap this
  7255.    error. However, you can set a depth limit on S-Expressions:
  7256.    
  7257.    SET SEXPRESSION DEPTH-LIMIT number
  7258.           Limits the number of times the S-Expression reader can invoke
  7259.           itself without returning to the given number. The default limit
  7260.           is 1000. This limit applies to S-Expressions embedded within
  7261.           other S-Expressions as well as to S-Expressions that invoke
  7262.           recursive macros. If the limit is exceeded, Kermit prints
  7263.           "?S-Expression depth limit exceeded" and returns to its prompt.
  7264.           More about recursion in [459]Section 9.8.
  7265.           
  7266.    You can also test the depth programmatically:
  7267.    
  7268.    \v(sdepth)
  7269.           The current S-Expression invocation depth. The depth includes
  7270.           both nesting level and recursion. For example, in:
  7271.           (foo (foo (foo (foo (foo))))), the innermost (foo) is at depth
  7272.           5.
  7273.           
  7274.    Help, completion, and syntax checking are not available within an
  7275.    S-Expression. If you type ? within an S-Expression, it says:
  7276.    
  7277.   C-Kermit>(? S-Expression ("help sexp" for details)
  7278.  
  7279.    As it says, typing "help sexp" will display a brief help text.
  7280.    
  7281.    The SHOW SEXPRESSION command displays current SET SEXPRESSION settings
  7282.    and related information.
  7283.    
  7284.    [ [460]Top ] [ [461]Contents ] [ [462]C-Kermit Home ] [ [463]Kermit
  7285.    Home ]
  7286.      _________________________________________________________________
  7287.    
  7288.   9.4. Summary of Built-in Constants and Operators
  7289.   
  7290.    Three constants are built in:
  7291.    
  7292.      * PI, whose value is the value of pi (the quotient of circumference
  7293.        of any circle and its diameter, 3.141592653...) to the underlying
  7294.        machine's precision;
  7295.      * T, which always has the value 1, which signifies truth in Kermit
  7296.        logical expressions or S-Expressions;
  7297.      * NIL, which always has the empty value, and can serve as a False
  7298.        truth value.
  7299.        
  7300.    These constants are specific to S-Expressions and are not visible
  7301.    outside them. They may not be used as the target of an assignment. So,
  7302.    for example:
  7303.    
  7304.   (setq t 0)   Fails
  7305.   assign t 0   Succeeds but this is not the same T!
  7306.  
  7307.    E (the base of natural logarithms, 2.7182818184...) is not built in
  7308.    since it is not intrinsic in most Lisp dialects. If you want E to be
  7309.    the base of natural logarithms you can:
  7310.    
  7311.   (setq e (exp 1))
  7312.  
  7313.    Operators are either symbols (such as "+") or words. Words must be
  7314.    spelled out in full, not abbreviated. Differences of alphabetic case
  7315.    are ignored.
  7316.    
  7317.    The most basic operation in S-Expressions is evaluation:
  7318.    
  7319.    EVAL [ s-expression or variable or number [ another [ another ... ] ]
  7320.           ]
  7321.           Evaluates its operands and returns the value of the last one
  7322.           evaluated. Examples:
  7323.           
  7324.   (eval)                                0
  7325.   (eval 1)                              1
  7326.   (eval a)                              value of a
  7327.   (eval (+ 1 a))                        value of a+1
  7328.   (eval (setq a 1) (setq b (+ a 0.5))   value of b (= a+0.5)
  7329.  
  7330.           You can use "." as a shorthand for EVAL:
  7331.           
  7332.   (.)
  7333.   (. 1)
  7334.   (. a)
  7335.   (. (+ 1 a))
  7336.   (. (setq a 1) (setq b (+ a 0.5))
  7337.  
  7338.    Opposite of EVAL is the operator that suppresses evaluation of its
  7339.    operand:
  7340.    
  7341.    QUOTE item
  7342.           The value (quote item) is "item". If the item is itself an
  7343.           S-Expression, the result is the S-Expression with the outer
  7344.           parentheses stripped. Examples:
  7345.           
  7346.   (quote)                               (illegal)
  7347.   (quote a)                             a
  7348.   (quote hello)                         hello
  7349.   (quote (this is a string))            this is a string
  7350.   (quote this is a string)              (illegal)
  7351.  
  7352.           A shorthand notation is also accepted for quoting:
  7353.           'a is equivalent to (quote a). And therefore:
  7354.           '(a b c) is equivalent to (quote (a b c)).
  7355.           More about quoting in [464]Section 9.8.
  7356.           
  7357.    STRING item
  7358.           Is a combination of EVAL and QUOTE. It evaluates the item as an
  7359.           S-Expression, and then puts quotes around the result (more
  7360.           about this in [465]Section 9.8).
  7361.           
  7362.    The following operators assign values to variables:
  7363.    
  7364.    SETQ [ variable [ value [ variable [ value [ ... ] ] ] ] ]
  7365.           Applies to global variables. For each variable given: if a is
  7366.           not given, the variable is undefined. If a value is given,
  7367.           assigns the value to the variable. The value may be a number, a
  7368.           variable, or anything that resolves to a number including an
  7369.           S-Expression. Returns the value of the last assignment.
  7370.           Examples:
  7371.           
  7372.   (setq)             Does nothing, returns NIL.
  7373.   (setq a)           Undefines a, returns NIL.
  7374.   (setq a 1)         Assigns 1 to a, returns 1.
  7375.   (setq a 1 b 2)     Assigns 1 to a, 2 to b, returns 2.
  7376.   (setq a 1 b 2 c)   Assigns 1 to a, 2 to b, undefines c, returns NIL.
  7377.  
  7378.    To undefine a variable that is not the final one in the list, give it
  7379.    a value of "()" or NIL:
  7380.    
  7381.   (setq a () b 2)    Undefines a, assigns 2 to b, returns 2.
  7382.   (setq a nil b 2)   Ditto.
  7383.  
  7384.    Note that a variable can be used right away once it has a value:
  7385.    
  7386.   (setq a 1 b a)     Assigns 1 to a, the value of a (1) to b, returns 1.
  7387.  
  7388.    The results of SETQ (when used with macro names) can be checked
  7389.    conveniently with SHOW MACRO, e.g:
  7390.    
  7391.   show mac a b c
  7392.  
  7393.    LET [ variable [ value [ variable [ value [ ... ] ] ] ] ]
  7394.           Like SETQ, but applies to local variables. Note that "local" is
  7395.           used in the Kermit sense, not the Lisp sense; it applies to the
  7396.           current Kermit command level, not to the current S-Expression.
  7397.           
  7398.    If you want to use SETQ or LET to assign a value to a backslash
  7399.    variable such as \%a or \&a[2], you must double the backslash:
  7400.    
  7401.   (setq \\%a 3)
  7402.   (setq \\%b (+ \%a 1))
  7403.   (setq \\&a[2] (setq (\\%c (+ \%a \%b))))
  7404.  
  7405.    In other words:
  7406.    
  7407.      * Double the backslash when you want to indicate the variable's
  7408.        NAME;
  7409.      * Don't double the backslash when you want its VALUE.
  7410.        
  7411.    See [466]Section 9.6 for a fuller explanation of variable syntax and
  7412.    scope.
  7413.    
  7414.    Here's a summary table of arithmetic operators; in the examples, a is
  7415.    2 and b is -1.3:
  7416.    
  7417.   Operator  Description                            Example           Result
  7418.   +         Adds all operands (0 or more)          (+ a b)           0.7
  7419.   -         Subtracts all operands (0 or more)     (- 9 5 2 1)       1
  7420.   *         Multiplies all operands (0 or more)    (* a (+ b 1) 3)  -1.80
  7421.   /         Divides all operands (2 or more)       (/ b a 2)        -0.325
  7422.   ^         Raise given number to given power      (^ 3 2)           9
  7423.   ++        Increments variables                   (++ a 1.2)        3.2
  7424.   --        Decrements variables                   (-- a)            1
  7425.   ABS       Absolute value of 1 operand            (abs (* a b 3))   7.8
  7426.   MAX       Maximum of all operands (1 or more)    (max 1 2 3 4)     4
  7427.   MIN       Minimum of all operands (1 or more)    (min 1 2 3 4)     1
  7428.   MOD (%)   Modulus of all operands (1 or more)    (mod 7 4 2)       1
  7429.   FLOAT     Convert an integer to floating-point   (float 1)         1.0
  7430.   TRUNCATE  Integer part of floating-point operand (truncate 3.333)  3
  7431.   CEILING   Ceiling of floating-point operand      (ceiling 1.25)    2
  7432.   FLOOR     Floor of floating-point operand        (floor 1.25)      1
  7433.   ROUND     Operand rounded to nearest integer     (round 1.75)      2
  7434.   SQRT      Square root of 1 operand               (sqrt 2)          1.414..
  7435.   EXP       e (2.71828..) to the given power       (exp -1)          0.367..
  7436.   SIN       Sine of angle-in-radians               (sin (/ pi 2))    1.0
  7437.   COS       Cosine of angle-in-radians             (cos pi)         -1.0
  7438.   TAN       Tangent of angle-in-radians            (tan pi)          0.0
  7439.   LOG       Natural log (base e) of given number   (log 2.7183)      1.000..
  7440.   LOG10     Log base 10 of given number            (log10 1000)      3.0
  7441.  
  7442.    The ++ and -- operators are also assignment operators and work just
  7443.    like SETQ and LET in their interpretations of operators and operands,
  7444.    but:
  7445.    
  7446.      * Each target variable must already be defined and have a numeric
  7447.        value;
  7448.      * The assignment value is the amount by which to increment or
  7449.        decrement the variable.
  7450.      * If an assignment value is not given, 1 is used.
  7451.        
  7452.    If you include more than one variable-value pair in a ++ or --
  7453.    expression, every variable (except, optionally, the last) must be
  7454.    followed by a value. Examples:
  7455.    
  7456.   (++ a)                Equivalent to (setq a (+ a 1)) and to (++ a 1)
  7457.   (++ a 2)              Equivalent to (setq a (+ a 2))
  7458.   (-- a (* 2 pi))       Equivalent to (setq a (- a (* 2 pi)))
  7459.   (++ a 1 b 1 c 1 d)    Equivalent to four SETQs incrementing a,b,c,d by 1.
  7460.  
  7461.    Another group of operators forms the predicates. These return a "truth
  7462.    value", in which 0 (or NIL) is false, and 1 or any other nonzero
  7463.    number is true.
  7464.    
  7465.   Operator  Description                            Example           Result
  7466.   = (or ==) Operands are equal                     (= 1 1.0)         1
  7467.   !=        Operands are not equal                 (!= 1 1.0)        0
  7468.   <         Operands in strictly ascending order   (< 1 2 3)         1
  7469.   <=        Operands in ascending order            ( 3 2 1)         1
  7470.   >=        Operands in descending order           (
  7471.  
  7472. The Exclusive OR of two values is true if one value is true and the other
  7473. value is false.
  7474.  
  7475. And another group operates on bits within an integer word:
  7476.  
  7477.   Operator  Description                            Example           Result
  7478.   &         Bitwise AND                            (& 7 2)           2
  7479.   |         Bitwise OR                             (| 1 2 3 4)       7
  7480.   #         Bitwise Exclusive OR                   (# 3 1)           2
  7481.   ~         Reverses all bits                      (~ 3)            -4
  7482.  
  7483.    These operators coerce their operands to integer by truncation if
  7484.    necessary. The result of bit reversal is hardware dependent.
  7485.    
  7486.    The final category of operator works on truth values:
  7487.    
  7488.   Operator  Description                            Example           Result
  7489.   IF        Conditional evaluation                 (if (1) 2 3)      2
  7490.  
  7491.    IF (predicate) (s1) [ (s2) ]
  7492.           The IF operator is similar to Kermit's IF command. If the
  7493.           predicate is true (i.e. evaluates to a nonzero number), the
  7494.           first S-Expression (s1) is evaluated and its value is returned.
  7495.           Otherwise, if (s2) is given, it is evaluated and its value
  7496.           returned; if (s2) is not given, nothing happens and the NIL
  7497.           (empty) value is returned.
  7498.           
  7499.    You can group multiple expressions in the s2 and s2 expressions using
  7500.    EVAL (or "."):
  7501.    
  7502.   (if (< a 0) (eval (setq x 0) (setq y 0)) (eval (setq x a) (setq y b)))
  7503.  
  7504.    or equivalently:
  7505.    
  7506.   (if (< a 0) (. (setq x 0) (setq y 0)) (. (setq x a) (setq y b)))
  7507.  
  7508.    Each operator has its own requirement as to number and type of
  7509.    operands. In the following table, "number" means any kind of number --
  7510.    integer or floating-point -- or a variable, function, macro, or
  7511.    S-Expression that returns a number; "vname" means variable name,
  7512.    "fpnumber" means a floating-point number (or anything that resolves to
  7513.    one), and "integer" means integer (or anything that resolves to one).
  7514.    "truthvalue" means anything that resolves to a value of zero or an
  7515.    empty value (which indicates false) or a nonzero value (which
  7516.    indicates true). "any" means any kind of value, including none at all.
  7517.    
  7518.   Operator  Number of operands   Type of operands    Returns
  7519.   EVAL  (.) 0 or more            S-Expression        Last value (default NIL)
  7520.   STRING    1                    S-Expression        string
  7521.   QUOTE (') 1                    word                string
  7522.   SETQ      0 or more            vname value pairs   Last value (default NIL)
  7523.   LET       0 or more            vname value pairs   Last value (default NIL)
  7524.   +         0 or more            number              number     (default 0)
  7525.   -         0 or more            number              number     (default 0)
  7526.   *         0 or more            number              number     (see note (1))
  7527.   /         2 or more            number              number
  7528.   ^         2 or more            number              number
  7529.   ++        1 or more            vname value pairs   Result of last increment
  7530.   --        1 or more            vname value pairs   Result of last decrement
  7531.   ABS       1                    number              number
  7532.   MAX       1 or more            number              number
  7533.   MIN       1 or more            number              number
  7534.   MOD (%)   2                    number              number
  7535.   FLOAT     1                    number              fpnumber
  7536.   TRUNCATE  1                    number              integer
  7537.   CEILING   1                    number              integer
  7538.   FLOOR     1                    number              integer
  7539.   ROUND     1                    number              integer
  7540.   SQRT      1                    number              fpnumber
  7541.   EXP       1                    number              fpnumber
  7542.   SIN       1                    number              fpnumber
  7543.   COS       1                    number              fpnumber
  7544.   TAN       1                    number              fpnumber
  7545.   LOG       1                    number              fpnumber
  7546.   LOG10     1                    number              fpnumber
  7547.   = (==)    1 or more            number              truthvalue
  7548.   !=        1 or more            number              truthvalue
  7549.   <         1 or more            number              truthvalue
  7550.   <=        1 or more            number              truthvalue
  7551.   >         1 or more            number              truthvalue
  7552.   >=        1 or more            number              truthvalue
  7553.   AND (&&)  1 or more            truthvalue          truthvalue
  7554.   OR  (||)  1 or more            truthvalue          truthvalue
  7555.   XOR       2                    truthvalue          truthvalue
  7556.   NOT (!)   1                    truthvalue          truthvalue
  7557.   &         1 or more            number (see note 2) integer
  7558.   |         1 or more            number (see note 2) integer
  7559.   #         2                    number (see note 2) integer
  7560.   ~         1                    number (see note 2) integer
  7561.   IF        2 or 3               truthvalue,any,any  any
  7562.  
  7563.    Operators that don't require any arguments return the default values
  7564.    shown.
  7565.    
  7566.     1. The value of "*", when used as an operator, is initially "1" and
  7567.        the value of the most recent S-Expression thereafter, as in Franz
  7568.        Lisp. This is handy when doing a series of calculations by hand:
  7569.  
  7570.   C-Kermit>(* 13272.42 0.40)
  7571.    5308.968
  7572.   C-Kermit>(/ * 2)
  7573.    2654.4840
  7574.   C-Kermit>
  7575.     2. The bitwise operators coerce their operands to integer by
  7576.        truncation.
  7577.        
  7578.    [ [467]Top ] [ [468]Contents ] [ [469]C-Kermit Home ] [ [470]Kermit
  7579.    Home ]
  7580.      _________________________________________________________________
  7581.    
  7582.   9.5. Variables
  7583.   
  7584.    As noted elsewhere in this discussion, all backslash items (variables
  7585.    such as \%a, macro parameters such as \%1, array elements such as
  7586.    \&a[\%i], built-in variables such as \v(ndate), built-in functions
  7587.    such as \fjoin(), macro names enclosed in \m(), \s(), or \:(), etc)
  7588.    are evaluated at "top level" before the S-Expression is sent to the
  7589.    S-Expression reader. To use a backslash variable as the target of an
  7590.    assignment (e.g. by SETQ, LET, ++, or --), you must double the
  7591.    backslash, e.g. (setq \\%r 1234). This is discussed at greater length
  7592.    in the next section.
  7593.    
  7594.    Thus S-Expression reader generally deals only with macro names (not
  7595.    backslash items) as variables. It is important to understand how the
  7596.    reader handles macro names. There are fundamentally two kinds of
  7597.    S-Expressions: those that contain a single element, such as:
  7598.    
  7599.   (foo)
  7600.  
  7601.    and those that contain more than one element:
  7602.    
  7603.   (foo a b c)
  7604.  
  7605.    If an S-Expression contains only one element, and it is the name of a
  7606.    macro, the macro's definition is examined. If the definition is a
  7607.    number (integer or floating-point, positive or negative), then this
  7608.    becomes the value of the expression. If the definition starts with '
  7609.    (apostrophe), then the quoted word or string is the value of the
  7610.    expression (explained in [471]Section 9.8). Otherwise, the macro is
  7611.    assumed to be composed of Kermit commands (possibly including
  7612.    S-Expressions), which are executed. If the macro has a RETURN value,
  7613.    or it executes an S-Expression as its last command, the result becomes
  7614.    the value of the S-Expression; otherwise the result is empty.
  7615.    
  7616.    For S-Expressions that contain more than one element, and the first
  7617.    element is the name of a macro, then this macro is executed with the
  7618.    arguments that are given, after the arguments are evaluated by the
  7619.    S-Expression reader. Likewise, If the first element is a built-in
  7620.    operator, then it is applied to the operands after they are evaluated.
  7621.    In both cases, each operand is fed to the S-Expression reader
  7622.    recursively for evaluation. If an operand is a number or a quoted
  7623.    string, it is used as-is. But if it's a macro name, this degenerates
  7624.    into the first case, and the previous paragraph applies.
  7625.    
  7626.    Examples:
  7627.    
  7628.   define foo 123
  7629.   (foo)                                Result: 123
  7630.   define foo 'abc
  7631.   (foo)                                Result: abc
  7632.   define foo '(one two three)
  7633.   (foo)                                Result: one two three
  7634.   define foo return \frandom(1000)
  7635.   (foo)                                Result: 713 (or other number)
  7636.   define foo (+ a b)
  7637.   (foo)                                Result: The sum of a and b
  7638.  
  7639.    A more difficult example:
  7640.    
  7641.   define foo abc
  7642.   (foo)                                Result: ???
  7643.  
  7644.    The result in the last example depends on the definition of abc:
  7645.    
  7646.      * If it has no definition, an error occurs; otherwise:
  7647.      * If the definition is an S-Expression, the result is the
  7648.        S-Expression's value; otherwise:
  7649.      * If the definition consists of Kermit commands, they are executed.
  7650.        But in this case "(foo)" produces the empty result, because it
  7651.        doesn't RETURN anything.
  7652.        
  7653.    The use of macros as S-Expression operators is described in
  7654.    [472]Section 9.8.
  7655.    
  7656.    [ [473]Top ] [ [474]Contents ] [ [475]C-Kermit Home ] [ [476]Kermit
  7657.    Home ]
  7658.      _________________________________________________________________
  7659.    
  7660.   9.6. Assignments and Scope
  7661.   
  7662.    The assignment operators SETQ and LET apply to global and local
  7663.    variables, respectively. SETQ and LET are standard Lisp operators
  7664.    adapted to Kermit scoping rules. When the operands are numeric or
  7665.    arithmetic, SETQ is equivalent to Kermit's EVALUATE command:
  7666.    
  7667.   (setq a (+ 1 2))
  7668.   evaluate a 1 + 2
  7669.  
  7670.    When the operand is a string, SETQ is equivalent to DEFINE:
  7671.    
  7672.   (setq a '(this is a string))
  7673.   define a this is a string
  7674.  
  7675.    In the first case, both statements create a macro named "a" with a
  7676.    value of 3. But in neither case is the macro "a" necessarily global.
  7677.    If either of these commands executes in an environment (i.e. macro
  7678.    invocation level) where a "local a" command has been given, the "a"
  7679.    macro is global to that environment, but is not visible outside it.
  7680.    
  7681.    LET is equivalent to the Kermit LOCAL command, followed by the
  7682.    corresponding EVALUATE:
  7683.    
  7684.   (let a (+ 1 2))
  7685.  
  7686.    is equivalent to:
  7687.    
  7688.   local a
  7689.   evaluate a 1 + 2
  7690.  
  7691.    Again, "local" in this context applies to the Kermit macro invocation
  7692.    stack, not to the S-Expression nesting level. To illustrate, recall
  7693.    our "newarea" macro:
  7694.    
  7695. def newarea {
  7696.     (let a \%1 b \%2 c \%3)
  7697.     (let s (/ (+ a b c) 2.0))
  7698.     (sqrt (* s (- s a) (- s b) (- s c)))
  7699. }
  7700.  
  7701.    Because SETQ and LET expressions return a value, they can be placed
  7702.    within a larger S-Expression. In this case we can replace the first
  7703.    reference to the "s" variable by its defining expression:
  7704.    
  7705. def newarea {
  7706.     (let a \%1 b \%2 c \%3)
  7707.     (sqrt (* (let s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c)))
  7708. }
  7709.  
  7710.    This would not work if LET were local to the S-Expression, but it
  7711.    works nicely in the context of Kermit macros. The previous definition
  7712.    is equivalent to:
  7713.    
  7714. def newarea {
  7715.     local a b c s
  7716.     (setq a \%1 b \%2 c \%3)
  7717.     (sqrt (* (setq s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c)))
  7718. }
  7719.  
  7720.    In both cases, the variables a, b, c, and s are local to the "newarea"
  7721.    macro, and global within it.
  7722.    
  7723.    Multiple assignments can be handled in several ways. Here is the
  7724.    obvious way to initialize a series of variables to the same value:
  7725.    
  7726.   (setq a 0)
  7727.   (setq b 0)
  7728.   (setq c 0)
  7729.   (setq s 0)
  7730.  
  7731.    Here is a more compact and efficient way of doing the same thing:
  7732.    
  7733.   (setq a 0 b 0 c 0 s 0)
  7734.  
  7735.    However, in case the value was more complex, it's better to put only
  7736.    one copy of it in the S-Expression; in this case we rely on the fact
  7737.    that SETQ returns the value of its last assignment:
  7738.    
  7739.   (setq a (setq b (setq c (setq s (* x (^ y 2))))))
  7740.  
  7741.    Similarly, to set a series of variables to x, x+1, x+2, ...
  7742.    
  7743.   (setq c (+ (setq b (+ (setq a (+ (setq s x) 1)) 1)) 1))
  7744.  
  7745.    In the last example, you can see why "last" does not always correspond
  7746.    to "rightmost" (the leftmost variable "c" is assigned last).
  7747.    
  7748.    If you are working with backslash variables like \%a or array elements
  7749.    like \&a[1], remember two rules:
  7750.     1. Don't put spaces inside array brackets.
  7751.     2. You must double the backslash when using SETQ, LET, ++, or -- to
  7752.        assign a value to a backslash variable.
  7753.        
  7754.    Examples of assigning to a backslash variable:
  7755.    
  7756.   (setq x 1)
  7757.   (setq \\%a 0)
  7758.   (setq \\&a[x+1] 1)
  7759.   (++ \\%x)
  7760.   (-- \\&a[x+2])
  7761.  
  7762.    Examples of referring to a backslash variable's value:
  7763.    
  7764.   (setq a (+ \%a 1))
  7765.   (setq b (+ \%a \&a[1]))
  7766.   (++ a \%x)
  7767.   (-- b \&a[1])
  7768.  
  7769.    The special notation is required because all backslashed items (\%x
  7770.    variables, array elements, built-in \v(xxx) variables, and \fxxx()
  7771.    function invocations) are evaluated in a single pass BEFORE the
  7772.    S-Expression is executed; any other approach would result in
  7773.    unacceptable performance. So, for example, in:
  7774.    
  7775.   declare \&a[] = 1 2 3
  7776.   define \%x 4
  7777.   define \%y 0
  7778.   (setq \\%y (+ \%x \&a[1]))
  7779.  
  7780.    the S-Expression becomes:
  7781.    
  7782.   (setq \%y (+ 4 1))
  7783.  
  7784.    before it is sent to the S-Expression evaluator. If the backslash had
  7785.    not been doubled on the assignment target, the result would have been:
  7786.    
  7787.   (setq 0 (+ 4 1))
  7788.  
  7789.    which is illegal because you can't assign a value to a number.
  7790.    Conversely, if backslashes were doubled on right-hand-side values:
  7791.    
  7792.   (setq \\%y (+ \\%x \\&a[1])
  7793.  
  7794.    this too, would give an error (not numeric - "\%x").
  7795.    
  7796.    If you omit the double backslash in the assignment target, the result
  7797.    depends on whether the variable already has a value:
  7798.    
  7799.   (setq \%a (* 3 3))
  7800.  
  7801.    If \%a has a non-numeric single-word value, then this becomes the name
  7802.    of the variable that is assigned by SETQ. To illustrate:
  7803.    
  7804.   define \%a foo
  7805.   echo \%a
  7806.   foo
  7807.   (setq \%a (* 3 3))
  7808.   echo \%a
  7809.   foo
  7810.   show macro foo
  7811.   foo = 9
  7812.  
  7813.    If \%a has no value, a numeric value, or a multiword value, an
  7814.    "invalid assignment" error occurs.
  7815.    
  7816.    [ [477]Top ] [ [478]Contents ] [ [479]C-Kermit Home ] [ [480]Kermit
  7817.    Home ]
  7818.      _________________________________________________________________
  7819.    
  7820.   9.7. Conditional Expressions
  7821.   
  7822.    The IF operator provides a compact form of decision-making within
  7823.    S-Expressions. An IF expression can stand wherever a number might
  7824.    stand, as long is it returns a number. Here's a quick way to obtain
  7825.    the average value of all the elements in an array that contains only
  7826.    numbers:
  7827.    
  7828.   (/ (+ \fjoin(&a)) (float \fdim(&a)))
  7829.  
  7830.    This results in a "Divide by zero" error if the array is empty. If you
  7831.    want to define the average value of an empty array to be 0 instead of
  7832.    getting an error, you can use IF to check the array size:
  7833.    
  7834.   (if \fdim(&a) (/ (+ \fjoin(&a)) (float \fdim(&a))) 0)
  7835.  
  7836.    or equivalently:
  7837.    
  7838.   (if (not \fdim(&a)) 0 (/ (+ \fjoin(&a)) (float \fdim(&a))))
  7839.  
  7840.    Of course, IF can fit anywhere else into an S-Expression:
  7841.    
  7842.   (setq a (+ b (if (< c 0) 0 c)
  7843.  
  7844.    and the IF expression can be as complex as you like:
  7845.    
  7846.   (setq a (+ b (if (and (or (> x 0) (> y 0)) (< c 0) (> d 1) (!= e 0)) 1 0)))
  7847.  
  7848.    and the "then" and "else" parts can contain multiple S-Expressions
  7849.    enclosed within (EVAL ...):
  7850.    
  7851.   (if x (eval (...) (...) (...)) (eval (...) (...) (...)))
  7852.  
  7853.    AND and OR operators are guaranteed to "short circuit". If any operand
  7854.    of AND is false, none of the subsequent operands is evaluated;
  7855.    likewise, if an OR operand is true, no further operands are evaluated.
  7856.    
  7857.    Bear in mind that the S-Expression IF is not the same as Kermit IF;
  7858.    the condition is only allowed to be an S-Expression or a variable or
  7859.    number, not the whole list of possibilities you see when you type "if
  7860.    ?" at the C-Kermit> prompt. But keep reading...
  7861.    
  7862.    [ [481]Top ] [ [482]Contents ] [ [483]C-Kermit Home ] [ [484]Kermit
  7863.    Home ]
  7864.      _________________________________________________________________
  7865.    
  7866.   9.8. Extensibility
  7867.   
  7868.    To extend the capabilities of S-Expressions, you can use Kermit macro
  7869.    names as operators, with the following limitations:
  7870.    
  7871.      * The macro must not have the same name as a built-in operator.
  7872.      * You must use the full macro name, not an abbreviation.
  7873.        
  7874.    And with the following enhancement:
  7875.    
  7876.      * If the last statement executed by the macro is an S-Expression,
  7877.        its value is returned automatically. In other words:
  7878.        
  7879.   define bump (++ \%1)
  7880.  
  7881.    is equivalent to:
  7882.    
  7883.   define bump return \fsexpression(++ \%1)
  7884.  
  7885.    Here's an example in which we define a FIBONACCI operator that returns
  7886.    the nth element, n > 0, of the Fibonacci series, 0 1 1 2 3 5 8 13 21
  7887.    34 55, . . ., in which the first element is 0, the second is 1, and
  7888.    each subsequent element is the sum of the two before it. This series
  7889.    was devised by Leonardo Pisano, Filius Bonacci (Fibonacci for short)
  7890.    in 1202 to describe how fast rabbits can breed, and also forms the
  7891.    basis for the Golden Mean, the branching behavior of plants, the
  7892.    spiral of a nautilus shell, etc.
  7893.    
  7894.    We can write a FIBONACCI function as a macro easily with
  7895.    S-Expressions:
  7896.    
  7897.   define FIBONACCI {
  7898.       (if (< \%1 3) (- \%1 1) (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1))))
  7899.   }
  7900.  
  7901.    You can read this as:
  7902.    
  7903.      If the argument (\%1) is less than 3, return the argument minus 1;
  7904.      otherwise:
  7905.      return the sum of fibonacci(argument - 2) and fibonacci(argument -
  7906.      1)
  7907.      
  7908.    Note that a RETURN statement is not needed, since S-Expressions
  7909.    automatically set the return value of their containing macros.
  7910.    
  7911.    For comparison, here's how it would be coded without S-Expressions:
  7912.    
  7913.   define FIBONACCI {
  7914.       if < \%1 3 return \feval(\%1-1)
  7915.       return \feval(\fexec(fibonacci \feval(\%1-2)) -
  7916.            + \fexec(fibonacci \feval(\%1-1)))
  7917.   }
  7918.  
  7919.    Now we can use the FIBONACCI function (whichever way you write it)
  7920.    just as if it were a built-in operator:
  7921.    
  7922.   (fibonacci 6)
  7923.  
  7924.    Or:
  7925.    
  7926.   (setq a 10)
  7927.   (fibonacci a)
  7928.  
  7929.    Within S-Expressions only (not outside them), S-Expressions themselves
  7930.    can be used as macro arguments:
  7931.    
  7932.   (setq a 2 b 4)
  7933.   (setq x (fibonacci (* a b )))
  7934.  
  7935.    The value of the S-Expression (in this case "8"), and not the
  7936.    S-Expression itself, is sent to the macro.
  7937.    
  7938.    Your macro is responsible for argument validation and error handling.
  7939.    A robust Fibonacci macro would be more like this:
  7940.    
  7941.   define FIBONACCI {
  7942.       if < \v(argc) 2 end 1 ?\%0: Missing argument
  7943.       if > \v(argc) 2 end 1 ?\%0: Too many arguments
  7944.       if not integer \%1 end 1 ?\%0: Integers only
  7945.       if < \%1 1 end 1 ?\%0: Argument out of range
  7946.       (if (< \%1 2) (\%1) (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1))))
  7947.   }
  7948.  
  7949.    Recall that "END nonzero-number [ message ]" causes a macro invocation
  7950.    to fail. When the macro is the operator in an S-Expression, this makes
  7951.    the S-Expression fail too. Also note that our Fibonacci macro is just
  7952.    an illustration, not a practical example. Since it is recursive (calls
  7953.    itself), it won't work for large arguments because the call stack can
  7954.    exceed available memory. See [485]Section 9.9.2 for a practical
  7955.    alternative.
  7956.    
  7957.    Kermit macros, when used as S-Expression operators, can do anything at
  7958.    all except initiate file transfers: they can print messages on the
  7959.    screen, read and write files, interact with the user, and so on. For
  7960.    example, here's a macro ASKME that asks you to enter a number, makes
  7961.    sure that you did, and then returns its value for use in the
  7962.    S-Expression:
  7963.    
  7964.   define ASKME {
  7965.       local \%n
  7966.       while true {
  7967.           ask \%n { Number: }
  7968.           if not def \%n continue
  7969.           if not numeric \%n {
  7970.               echo Not numeric - "\%n"
  7971.               continue
  7972.           }
  7973.           break
  7974.       }
  7975.       return \%n
  7976.   }
  7977.   (setq a (* 2 (askme)) ; Get number from user, double it, assign result to a.
  7978.  
  7979.    Here's a macro you can use to validate that a number is in a given
  7980.    range:
  7981.    
  7982.   define inrange {
  7983.       if != \v(argc) 4 end 1 ?\%0: Wrong number of arguments
  7984.       if ( < \%1 \%2 || > \%1 \%3 ) return 0
  7985.       return 1
  7986.   }
  7987.  
  7988.    The first argument is the number to be checked, the second is the
  7989.    minimum acceptable value, the third is the maximum. You can use this
  7990.    (for example) in IF conditions:
  7991.    
  7992.   define yes echo \%1 IS OK
  7993.   define no echo \%1 IS NOT OK
  7994.  
  7995.   (setq a -1 b 999)
  7996.   (if (inrange a 0 100) (yes a) (no a))
  7997.   (if (inrange b -1000 +1000) (yes b) (no b))
  7998.  
  7999.    This is just an illustration, of course; there's already a built-in
  8000.    operator to let you do range checking without help from macros:
  8001.    
  8002.   (if (<= 0 a 100) (yes a) (no a))
  8003.   (if (<= -1000 b +1000) (yes b) (no b))
  8004.  
  8005.    To send string parameters to a macro, some kind of quoting is required
  8006.    to tell the S-Expression parser to take a given "word" literally
  8007.    rather than replacing it by its value. For this we use the Lisp QUOTE
  8008.    operator:
  8009.    
  8010.   define length return \flength(\%1)
  8011.   (length (quote abcdefghijklmnopqrstuvwxyz))
  8012.   26
  8013.  
  8014.    This causes the string "abcdefghijklmnopqrstuvwxyz" to be sent
  8015.    literally to the LENGTH macro. Kermit, like Lisp, also offers a
  8016.    shortcut for QUOTE, that lets us quote a word by prefixing it with a
  8017.    single quote (') character, also called apostophe (ASCII 39):
  8018.    
  8019.   (length 'abcdefghijklmnopqrstuvwxyz)
  8020.   26
  8021.  
  8022.    The two forms are equivalent.
  8023.    
  8024.    How the macro treats its arguments is up to the macro. In the example
  8025.    above, the argument is treated as a literal string. However, it can
  8026.    also be treated as a variable name:
  8027.    
  8028.   define string This is a string
  8029.   define length return \flength(\m(\%1))
  8030.   (length 'string)
  8031.   16
  8032.  
  8033.    Note the construct \m(\%1). This means "the value of the macro whose
  8034.    name is the value of
  8035.    \%1". The value of \%1 in this case is the word "string", and the
  8036.    value of the macro whose name is "string" is "This is a string".
  8037.    
  8038.    What if the macro takes multiple arguments, or a variable number of
  8039.    them? Here's a simple macro that prints a phrase that includes its
  8040.    arguments:
  8041.    
  8042.   define complain echo It's too \%*!
  8043.  
  8044.    (Recall that \%* means "all arguments".)
  8045.    
  8046.    It can be called in the traditional way:
  8047.    
  8048.   complain hot                       Result: "It's too hot!"
  8049.   complain cold and wet              Result: "It's too cold and wet!"
  8050.  
  8051.    Or from an S-Expression if you quote the arguments:
  8052.    
  8053.   (complain 'hot)                    Result: "It's too hot!"
  8054.   (complain 'cold 'and 'wet)         Result: "It's too cold and wet!"
  8055.  
  8056.    To group multiple words into a single argument, use parentheses:
  8057.    
  8058.   (complain (quote (cold and wet)))  Result: "It's too cold and wet!"
  8059.   (complain '(cold and wet))         Result: "It's too cold and wet!"
  8060.  
  8061.    Note the difference:
  8062.    
  8063.   (complain 'cold 'and 'wet)         Three arguments
  8064.   (complain '(cold and wet))         One argument
  8065.  
  8066.    Since the COMPLAIN macro uses \%* to refer to all its arguments, no
  8067.    matter how many, it doesn't care which form you use. But it makes a
  8068.    difference in cases where the macro refers to its arguments
  8069.    individually.
  8070.    
  8071.    To illustrate, let's consider a macro that receives the name of a
  8072.    macro and its argument list and executes it with its arguments,
  8073.    without knowing how many arguments there are. The following LOOP macro
  8074.    is used to execute the given macro with the given argument list the
  8075.    requested number of times:
  8076.    
  8077.   def loop { local i, for i 1 \%1 1 do \%2 \%3 }
  8078.  
  8079.    Within the LOOP macro, the first argument (\%1) is the loop count, \%2
  8080.    is the macro name, and \%3 is the argument list. When the LOOP macro
  8081.    is invoked traditionally like this:
  8082.    
  8083.   loop 3 complain hot
  8084.  
  8085.    it prints "It's too hot!" three times. To invoke it from an
  8086.    S-Expression, you must quote both the macro name as well as the
  8087.    argument, since in this case the macro name itself is an argument:
  8088.    
  8089.   (loop 3 'complain 'hot)
  8090.  
  8091.    Now what if you need to send different or variable numbers of
  8092.    arguments to the LOOP macro? The LOOP macro can handle it already,
  8093.    provided you group the arguments into LOOP's third argument (\%3). In
  8094.    Kermit syntax, without grouping:
  8095.    
  8096.   loop 3 complain cold and wet
  8097.  
  8098.    prints "It's too cold!" three times ("and wet" is lost); but with
  8099.    grouping (either of the following two forms):
  8100.    
  8101.   loop 3 complain {cold and wet}
  8102.   loop 3 complain "cold and wet"
  8103.  
  8104.    the LOOP macro prints "It's too cold and wet!" three times as desired.
  8105.    
  8106.    To do the same thing in an S-Expression, just use the Lisp forms of
  8107.    quoting instead of the Kermit forms; the following two are equivalent:
  8108.    
  8109.   (loop 3 'complain (quote (cold and wet)))
  8110.   (loop 3 'complain '(cold and wet))
  8111.  
  8112.    Here's a similar example in which we write a macro that shows both the
  8113.    name and the value of one or more other macros, whose names are given
  8114.    as arguments (similar to "show macro"):
  8115.    
  8116.   define display {
  8117.       local \%i
  8118.       for \%i 1 \v(argc)-1 1 {
  8119.           echo \&_[\%i] = \m(\&_[\%i])
  8120.       }
  8121.   }
  8122.  
  8123.    (Recall that \&_[] is the macro's argument vector array, equivalent to
  8124.    \%1, \%2, ...) The DISPLAY macro can be used in S-Expressions like
  8125.    this:
  8126.    
  8127.   (setq a 1 b 2 c 3)
  8128.   (display 'a 'b 'c 'd)
  8129.  
  8130.    which prints:
  8131.    
  8132.   a = 1
  8133.   b = 2
  8134.   c = 3
  8135.   d =
  8136.  
  8137.    The names must be quoted to prevent their evaluation before they are
  8138.    sent to the macro. This ability to pass variables "by name" to macros,
  8139.    rather than by value, lets you write macros that change the values of
  8140.    argument variables. For example, here's a macro that doubles the value
  8141.    of its argument variable:
  8142.    
  8143.   define double (++ \%1 \%1)
  8144.  
  8145.    which you can call like this:
  8146.    
  8147.   (setq a 12)
  8148.   (double 'a)
  8149.  
  8150.    In the macro, \%1 is replace by the variable name "a"; "(++ a a)" adds
  8151.    "a" to itself, and sets the value of "a" to the result.
  8152.    
  8153.    There are no built-in operators other than QUOTE, ', and STRING for
  8154.    handling strings in S-Expressions, but using just these, plus macros
  8155.    that use Kermit's regular string-handling features, you can easily
  8156.    extend S-Expressions to do string manipulation:
  8157.    
  8158.   define len return \flen(\%1)               Returns length of argument string
  8159.   define cap return \fupper(\%1)             Uppercase argument string
  8160.   define rev return \freverse(\%1)           Reverses argument string
  8161.   define sub return \fsubstr(\%1,\%2,\%3)    Returns substring of arg string
  8162.  
  8163.   (len '(this is a string))                  Result: 16
  8164.   (rev '(this is a string))                  Result: gnirts a si siht
  8165.   (rev (cap '(this is a string)))            Result: GNIRTS A SI SIHT
  8166.   (sub (rev (cap '(this is a string))) 5 9)  Result: TS A SI S
  8167.  
  8168.    You can assign a string to a macro name as follows:
  8169.    
  8170.   (setq foo '(this is a string)))
  8171.   (setq foo (quote (this is a string))))
  8172.  
  8173.    The two are exactly equivalent. In both cases, the macro "foo" has the
  8174.    value:
  8175.    
  8176.   '(this is a string)
  8177.  
  8178.    so when it is retrieved it can be identified as a string rather than a
  8179.    number or commands to be executed. Thus:
  8180.    
  8181.   (setq foo (quote (this is a string))))
  8182.   show macro foo
  8183.   foo = '(this is a string)
  8184.   (foo)
  8185.   this is a string
  8186.  
  8187.    Note the different results for "show macro foo" and "(foo)". The
  8188.    former shows the internal definition; the latter evaluates the
  8189.    variable, which removes the quoting. And perhaps more important, note
  8190.    that if the apostrophe and surrounding parentheses were not stored as
  8191.    part of the definition, (foo) would try to execute "this is a string"
  8192.    as a command.
  8193.    
  8194.    Given the assignment above, the following work as expected:
  8195.    
  8196.   (len foo)                                  Result: 16
  8197.   (rev foo)                                  Result: gnirts a si siht
  8198.   (rev (cap foo))                            Result: GNIRTS A SI SIHT
  8199.   (sub (rev (cap foo)) 5 8)                  Result: TS A SI S
  8200.  
  8201.    Note that, unlike built-in S-Expression operators that return numbers
  8202.    or truth values, these operators return strings. If you want to assign
  8203.    their return values to other variables, you can do so:
  8204.    
  8205.   (setq bar (rev (cap foo)))                 Result: GNIRTS A SI SIHT
  8206.  
  8207.    But now the S-Expression processor doesn't know the value of "bar" is
  8208.    supposed to be a string, rather than a macro to execute. For this you
  8209.    need one final special operator, STRING. The STRING operator takes an
  8210.    S-Expression as an operand, evaluates it, and then returns its value
  8211.    enclosed in '(), so you can use the value as a string is subsequent
  8212.    S-Expressions. Use STRING for referencing macros that return strings:
  8213.    
  8214.   (setq bar (string (rev (cap foo))))        Result: '(GNIRTS A SI SIHT)
  8215.  
  8216.    STRING is like QUOTE, except that it evaluates its operand before
  8217.    applying the quoting, rather than taking the operand literally.
  8218.    
  8219.    To reference backslash variables or functions that return string
  8220.    values, you must use the regular quoting mechanisms:
  8221.    
  8222.   (setq time '(\v(time)))
  8223.   (setq date '(\v(date)))
  8224.   assign \%r this is a string
  8225.   (setq s1 '(\%r))
  8226.  
  8227.    That's because backslash items are evaluated BEFORE the S-Expression
  8228.    parser ever sees them, and the values of \v(time) and so on are not
  8229.    valid S-Expressions, so STRING won't like them.
  8230.    
  8231.    Finally a brief word on the touchy topic of quoting. Suppose you want
  8232.    to include (say) literal parentheses in a string that will later be
  8233.    processed by the S-Expression reader (or \fsplit() or \fword()).
  8234.    Normally, you can't do this because parentheses are meaningful in
  8235.    these contexts. To defeat the normal parsing rules, you can quote the
  8236.    parentheses with backslash. However, due to the many levels of string
  8237.    processing involved, a surprisingly large amount of backslashes might
  8238.    be required, for example:
  8239.    
  8240.   (setq s '(a b (c d) \\\\\\\\\\\\\\\\(e f (g h) x\\\\\\\\\\\\\\\\) j k))
  8241.  
  8242.    This is nearly impossible to explain(*). Instead, just remember two
  8243.    points:
  8244.    
  8245.      * In situations like this, it's better to use DEFINE to create the
  8246.        string, rather than SETQ. The example above requires only double
  8247.        backslashes when DEFINE is used:
  8248.  
  8249.   define s '(a b (c d) \\(e f (g h) x\\j k))
  8250.      * The level of quoting depends on how many levels of evaluation the
  8251.        string must pass through, which is not always obvious. However,
  8252.        the number of backslashes required in any given situation is
  8253.        always a power of 2. So if 1 doesn't work, try 2; if 2 doesn't
  8254.        work, try 4; if 4 doesn't work, try 8, 16, 32, and so on.
  8255.        
  8256.    Considerations like this apply in any scripting language (shell, Tcl,
  8257.    Perl, Python, etc). The situation is known as "Quoting Hell".
  8258.    
  8259.    (*) If you really want an explanation, here it is:
  8260.    
  8261.      * Every SEXP has its backslash items evaluated in a single pass at
  8262.        top level before being passed to the SEXP reader, so \%1,
  8263.        \v(ftime), etc, can be evaluated up front, freeing the SEXP reader
  8264.        of having to know about such things, which in turn makes it much
  8265.        more efficient. Therefore one level of quoting is lost right away,
  8266.        and therefore you must double each backslash that is to be used as
  8267.        a quote.
  8268.      * When the SEXP reader sees '\', it treats it as a quote; discards
  8269.        it and keeps the next character. Thus '\\' becomes '\'. This would
  8270.        be the end of it, except that:
  8271.      * The SEXP reader must call itself recursively on its operands, so
  8272.        we must double any quotes in the operands: 2^2 = 4.
  8273.      * If the result is to be passed as an argument to a macro, the
  8274.        backslashes must again be doubled, because the macro processor
  8275.        evaluates the arguments before sending them to the macro: 2^3 = 8.
  8276.      * If the macro itself is to see the quotes, rather than just the
  8277.        result of the quoting, the quotes must be doubled again: 2^4 = 16.
  8278.        
  8279.    Moral: To create string constants in which grouping characters must be
  8280.    quoted, use DEFINE rather than SETQ.
  8281.    
  8282.    [ [486]Top ] [ [487]Contents ] [ [488]C-Kermit Home ] [ [489]Kermit
  8283.    Home ]
  8284.      _________________________________________________________________
  8285.    
  8286.   9.9. Examples
  8287.   
  8288.     9.9.1. Statistics
  8289.     
  8290.    The following program computes statistics -- means, maxima, mimima,
  8291.    variance, standard deviation, and correlation -- from data stored in
  8292.    parallel arrays, \&x[] and \&y[], which can contain any mixture of
  8293.    integer and floating-point numbers: positive, negative, or zero. Array
  8294.    setup and validation are not shown. Except for the traditional FOR
  8295.    loop and printing the results at the end, the entire computation is
  8296.    done with S-Expressions:
  8297.    
  8298. ; Initialize sums, maxima, minima, and number of elements
  8299.  
  8300.   (setq xsum 0 ysum 0 xsum2 0 ysum2 0 xysum 0)
  8301.   (setq xmin (setq xmax \&x[1]) ymin (setq ymax \&y[1]))
  8302.   (setq n \fdim(&x))
  8303.  
  8304. ; Loop through elements and accumulate sums, maxima, and minima
  8305.  
  8306.   for i 1 n 1 {
  8307.       (setq x \&x[i] y \&y[i])                    ; Notational convenience
  8308.       (setq xmax (max xmax x) ymax (max ymax y))  ; X and Y maxima
  8309.       (setq xmin (min xmin x) ymin (min ymin y))  ; X and Y minima
  8310.       (++ xsum x ysum y)                          ; X and Y sums
  8311.       (++ xsum2 (^ x 2) ysum2 (^ y 2))            ; Sum of X and Y squares
  8312.       (++ xysum (* x y))                          ; Sum of XY products
  8313.   }
  8314.  
  8315. ; Calculate results
  8316.  
  8317.   (setq xmean (/ xsum n) ymean (/ ysum n))        ; Mean X and Y
  8318.   (setq xss (- xsum2 (/ (^ xsum 2) n)))           ; Intermediate values
  8319.   (setq yss (- ysum2 (/ (^ ysum 2) n)))
  8320.   (setq xyss (- xysum (/ (* xsum ysum) n)))
  8321.   (setq xvar (/ xss n) yvar (/ yss n))            ; X and Y variance
  8322.   (setq sdx (sqrt xvar) sdy (sqrt yvar))          ; Std deviation in X and Y
  8323.   (setq tmp (* xss yss))
  8324.   (setq cc (if tmp (/ xyss (sqrt tmp)) 1.0))      ; Correlation coefficient
  8325.   show macro xmean ymean xvar yvar sdx sdy cc     ; Print the results
  8326.  
  8327.    The final "if tmp" check accounts for the possibility that both arrays
  8328.    contain all 0's. Results can also be printed with "echo CC = \m(cc)",
  8329.    or any other desired way. Interestingly, if we had not needed the sum
  8330.    of the squares and products, we could have obtained the sums, maxima,
  8331.    and minima of the X's and Y's without a loop like this:
  8332.    
  8333.   (setq xsum (+ \fjoin(&x)) ysum (+ \fjoin(&y))
  8334.   (setq xmax (max \fjoin(&x)) ymax (max \fjoin(&y))
  8335.   (setq xmin (min \fjoin(&x)) ymin (min \fjoin(&y))
  8336.  
  8337.    Any Kermit function that returns numbers or lists of numbers can be
  8338.    included in an S-Expression as an operand.
  8339.      _________________________________________________________________
  8340.    
  8341.     9.9.2. Practical Fibonacci Series
  8342.     
  8343.    The recursive Fibonacci example given previously is simple and
  8344.    elegent, but not very useful since it causes memory occupation to grow
  8345.    each time it calls itself, until eventually both physical memory and
  8346.    disk swap space are filled and the program crashes. Even for small
  8347.    arguments, like 17, execution time can be prohibitive:
  8348.    
  8349.   (setq t1 \v(ftime))
  8350.   (setq result (fibonacci 17))
  8351.   (setq t2 (- \v(ftime) t1))
  8352.   echo FIBONACCI(17) = \m(result): TIME = \ffpround(t2,3)
  8353.  
  8354.    prints (on a certain rather slow computer):
  8355.    
  8356.   FIBONACCI(17) = 987: TIME = 27.544
  8357.  
  8358.    Any recursive function can be recoded iteratively. The result is not
  8359.    as pretty, but execution is far less expensive:
  8360.    
  8361.   define FIBONACCI {
  8362.       local i n r s
  8363.       (setq n \%1 r 1 s 0)
  8364.       if < n 3 return \fsexp(-- n)
  8365.       for i 3 n 1 { (setq tmp r r (+ r s) s tmp) }
  8366.       (r)
  8367.   }
  8368.  
  8369.    Here's the result on the same computer for the same argument of 17:
  8370.    
  8371.   FIBONACCI(17) = 987: TIME = 0.125
  8372.  
  8373.    (220 times faster.) Execution time increases proportionally to the
  8374.    size of the argument in the iterative case, whereas in the recursive
  8375.    case it goes up geometrically, quickly reaching infinity.
  8376.    
  8377.    [ [490]Top ] [ [491]Contents ] [ [492]C-Kermit Home ] [ [493]Kermit
  8378.    Home ]
  8379.      _________________________________________________________________
  8380.    
  8381.   9.10. Differences from Algebraic Notation
  8382.   
  8383.    In C-Kermit:
  8384.    
  8385.      * Algebraic notation uses infix operators and normal rules of
  8386.        operator precedence, with parentheses used to force exceptions to
  8387.        the rules; many operations can be included in an expression.
  8388.        S-Expressions use prefix operators with no intrinsic precedence;
  8389.        each operation is enclosed in parentheses, and the arrangement of
  8390.        parentheses determines precedence.
  8391.      * Algebraic infix operators require two operands; S-Expression
  8392.        prefix operators can accept a variable number of operands.
  8393.      * You can use algebraic notation anywhere that C-Kermit accepts a
  8394.        number, e.g. "echo \&a[((1+1)*2-1]", but you can use S-Expressions
  8395.        only as top-level commands. You can, however, use either algebraic
  8396.        or S-Expressions anywhere at all by enclosing them in \fevaluate()
  8397.        or \fsexpression(), respectively.
  8398.      * You can use any mixture of integer and floating-point numbers in
  8399.        S-Expressions, but only integers are permitted in algebraic
  8400.        expressions. Outside of S-Expressions, floating point arithmetic
  8401.        is supported only by \ffp...() function calls.
  8402.      * Operators and operands in S-Expressions must be separated by
  8403.        spaces, e.g. "(+ a b)". Spaces are not required in algebraic
  8404.        expressions: "((a+b)*c)".
  8405.      * When assigning values to backslash variables (such as \%x or
  8406.        \&a[2]) using SETQ or LET, you must double the backslash.
  8407.        
  8408.    [ [494]Top ] [ [495]Contents ] [ [496]C-Kermit Home ] [ [497]Kermit
  8409.    Home ]
  8410.      _________________________________________________________________
  8411.    
  8412.   9.11. Differences from Lisp
  8413.   
  8414.      * Kermit has a lot of built-in operators not found in Lisp: ++, ^,
  8415.        etc.
  8416.      * Most dialects of real Lisp do not allow S-Expressions that don't
  8417.        start with an operator, for example:
  8418.  
  8419.   (a)
  8420.        This expression can cause an error in Lisp (even if "a" has a
  8421.        value), but is acceptable in Kermit, where it returns the value of
  8422.        the variable "a". Similarly, (1) returns the value "1".
  8423.      * In real Lisp, EVAL requires exactly one operand. In Kermit, it can
  8424.        have 0, 1, 2, or more operands. It returns the value of the last
  8425.        operand evaluated.
  8426.      * Real Lisp SETQ and LET usually require an even number of operands.
  8427.        Kermit allows an odd number, in which case the last (or only)
  8428.        variable is undefined (i.e. deleted, destroyed).
  8429.      * Kermit does not support ratios such as "7/8". Some Lisp dialects
  8430.        accept ratios as numbers, and generate ratios when told to divide
  8431.        two integers whose quotient is not a whole number; e.g. in Common
  8432.        Lisp:
  8433.  
  8434.   [13] USER(37): (/ (+ 1 2 3 4) 3)
  8435.   10/3
  8436.   [13] USER(38):
  8437.      * The result of (/ 10 3) is 3.333.... Some Lisp dialects truncate
  8438.        the result to 3 since both operands are integers, some don't; some
  8439.        give the result as a ratio. C-Kermit always gives a floating point
  8440.        result when there is a fractional part. If you want an integer
  8441.        result, you can use TRUNCATE, FLOOR, or CEILING, e.g. (truncate (/
  8442.        10 3)).
  8443.      * There is currently no "bignum" support. Large numbers can be used
  8444.        and large results generated, but (as noted in [498]Section 9.2)
  8445.        they are accurate only to the precision of the underlying machine.
  8446.        \v(math_precision) gives the machine precision as a number of
  8447.        decimal digits, e.g. 16.
  8448.      * Scientific notation for floating-point numbers is not supported.
  8449.        If the magnitude of a number is greater than the precision of the
  8450.        underlying hardware, the less-significant digits are shown but
  8451.        their values are meaningless. If it the number is too small to be
  8452.        represented internally, it is shown as "0.0".
  8453.      * Many Lisp features are omitted: List processing (CAR, CDR, etc),
  8454.        DEFUN, Lisp-specific control structures, and so on.
  8455.        
  8456.    [ [499]Top ] [ [500]Contents ] [ [501]C-Kermit Home ] [ [502]Kermit
  8457.    Home ]
  8458.    
  8459. 1
  8460.   __________________________________________________________________________
  8461.  
  8462. 10. FILE TRANSFER
  8463.  
  8464.    New commands and switches:
  8465.    
  8466.    SEND /TYPE:{TEXT,BINARY}
  8467.           Sends only files of the given type (see [503]Section 4).
  8468.           
  8469.    SEND /NOFOLLOWLINKS:
  8470.           (UNIX only) Skip over symbolic links rather than following them
  8471.           (default). This applies to wildcard and/or recursive SENDs; if
  8472.           a single filename is given, and it happens to be a symbolic
  8473.           link, the file it points to is sent.
  8474.           
  8475.    SEND /FOLLOWLINKS:
  8476.           (UNIX only) Follow (resolve) symbolic links. Watch out for
  8477.           circular links, endless loops, etc.
  8478.           
  8479.    SET SEND I-PACKETS { OFF, ON }
  8480.           When sending commands to a Kermit server, this tells whether
  8481.           command packets should be preceded by an I (information)
  8482.           packet, which is used to synchronize parameters prior to
  8483.           executing the command. Normally ON. The only reason to set this
  8484.           OFF is for communicating with buggy Kermit servers that
  8485.           misbehave when an I packet is sent to them. There is also a SET
  8486.           RECEIVE I-PACKETS command, but presently it has no effect.
  8487.           
  8488.    SET TRANSFER MESSAGE [ text ]
  8489.           Sets an initial message to be shown in the Last Message field
  8490.           of the fullscreen file-transfer display.
  8491.           
  8492.    SET TRANSFER TRANSLATION { ON, OFF }
  8493.           Inhibits or re-enables text-file transfer character-set
  8494.           translation globally.
  8495.           
  8496.    { SEND, MSEND, GET, RECEIVE } /TRANSPARENT
  8497.           Inhibits character-set translation for this transfer only.
  8498.           
  8499.    { GET, RECEIVE } /PIPES:{ON,OFF}
  8500.           Overrides global TRANSFER PIPES setting for this transfer only;
  8501.           ON allows incoming files with names like "!tar xf -" to be
  8502.           opened as pipelines rather than regular files.
  8503.           
  8504.    The following new "hot keys" are available when Kermit's file-transfer
  8505.    display is visible:
  8506.    
  8507.      D: Turn on debugging, open "debug.log" if not already open.
  8508.      d: Turn off debugging but leave log open (if it was open).
  8509.      T: Turn on debug-log timestamps.
  8510.      t: Turn off debug-log timestamps.
  8511.    
  8512.    Other improvements:
  8513.      * SET FILE DOWNLOAD-DIRECTORY now works for external protocols (e.g.
  8514.        sz/rz) too.
  8515.      * Improved automatic per-file text/binary switching, described in
  8516.        [504]Section 4.
  8517.      * When sending a file group (e.g. "send *.*"), failure to open a
  8518.        file is no longer fatal; now C-Kermit simply goes ahead to the
  8519.        next file.
  8520.      * Transaction log entries are now made for external protocols too.
  8521.        
  8522.    [ [505]Top ] [ [506]Contents ] [ [507]C-Kermit Home ] [ [508]Kermit
  8523.    Home ]
  8524.   __________________________________________________________________________
  8525.  
  8526. 11. MODEMS AND DIALING
  8527.  
  8528.    In C-Kermit 8.0, the default modem type for dialing has changed from
  8529.    NONE (= DIRECT, meaning no modem) to GENERIC. This change should have
  8530.    no impact on direct connections. For dialing, it means that, unless
  8531.    you SET MODEM TYPE to a specific type, such as USROBOTICS or CONEXANT,
  8532.    Kermit assumes:
  8533.    
  8534.     1. The modem uses the Hayes AT command set.
  8535.     2. The modem supports error correction, data compression, and
  8536.        hardware flow control and is already configured to use them.
  8537.        
  8538.    In fact, Kermit assumes the modem is completely configured, and
  8539.    therefore does not send it an initialization string or any
  8540.    configuration commands. Instead, it sends only the simplest and most
  8541.    portable commands:
  8542.    
  8543.      ATQ0V1          Give dial result codes.
  8544.      ATDTnumber      Dial the number.
  8545.    
  8546.    (or ATD or ATDP, as appropriate).
  8547.    
  8548.    The new defaults work for direct connections and for most modern
  8549.    modems on most platforms, and they work much faster than
  8550.    "full-treatment" dialing. If the new defaults don't work for you, or
  8551.    if you need to perform explicit modem configuations or interactions,
  8552.    then set a specific modem type and use the SET MODEM and SET DIAL
  8553.    commands as documented in Using C-Kermit.
  8554.    
  8555.      WARNING: Don't use the generic modem on hosts that do not support
  8556.      RTS/CTS flow control. If Xon/Xoff is in use on the serial port,
  8557.      you'll need to select a particular modem type so Kermit knows what
  8558.      command to give it to enable Xon/Xoff flow control between itself
  8559.      and your serial port.
  8560.      
  8561.    The following new modem types were added in C-Kermit 8.0:
  8562.    
  8563.      lucent:          Lucent Venus chipset
  8564.      pctel:           PCTel V.90 chipset
  8565.      conexant:        Conexant (ex-Rockwell) modem family
  8566.      zoom-v32bis:     New name for "Zoom"
  8567.      zoom-v34         Zoom V.34
  8568.      zoom-v90         Zoom V.90 56K
  8569.      zoom-v92:        Zoom V.92 with V.44 data compression
  8570.      zoltrix-v34:     New name for "zoltrix"
  8571.      zoltrix-hsp-v90: Synonym for PCTel
  8572.      zoltrix-hcf-v90: Synonym for ITU-T-V250
  8573.      smartlink-v90:   Synonym for usrobotics (same chipset)
  8574.      acer-v90:        Synonym for Rockwell-v90
  8575.    
  8576.    New DIAL-related variables:
  8577.    
  8578.      \v(dm_hf):  Dial modifier: Wait for Hook-Flash.
  8579.      \v(dm_wb):  Dial modifier: Wait for Bong.
  8580.    
  8581.    Finally, if dialing fails, Kermit now prints a context-sensitive hint
  8582.    suggesting possible reasons and remedies.
  8583.    
  8584.    Added in C-Kermit 8.0.201:   Rudimentary support for Caller ID, for
  8585.    use with the ANSWER command. If the modem reports Caller ID
  8586.    information, Kermit stores it in variables that you can access after
  8587.    the call is answered:
  8588.    
  8589.   \v(callid_date)   The date of the call
  8590.   \v(callid_time)   The time of the call
  8591.   \v(callid_name)   The name of the caller
  8592.   \v(callid_nmbr)   The telephone number of the caller
  8593.   \v(callid_mesg)   A message
  8594.  
  8595.    The format of these items depends on the originating and answering
  8596.    phone companies and the modems and their configuration.
  8597.    
  8598.    Not very many modems support Caller ID, and those that do (a) tend to
  8599.    have it disabled by default, and (b) use different commands to enable
  8600.    it. A quick survey shows of some current models shows:
  8601.    
  8602.    - USR V.90:      No
  8603.    - ITU-T V.250:   No
  8604.    - Lucent Venus:  No
  8605.    - Diamond Supra: #CID=1
  8606.    - Rockwell 56K:  #CID=1
  8607.    - PCTEL:         #CID=1
  8608.    - Zoltrix:       +VCID=1
  8609.    - Conexant:      +VCID=1
  8610.  
  8611.    To use Kermit's Caller ID feature, you have to set the modem to wait
  8612.    for at least two rings before answering, and you have to give the
  8613.    command to enable Caller ID; for example (after choosing a modem with
  8614.    SET MODEM TYPE):
  8615.    
  8616.   set modem command autoanswer on ATS0=2#CID=1\{13}
  8617.   set modem command autoanswer on ATS0=2+VCID=1\{13}
  8618.  
  8619.    These commands can be undone with:
  8620.    
  8621.   set modem command autoanswer on ATS0=1#CID=0\{13}
  8622.   set modem command autoanswer on ATS0=1+VCID=0\{13}
  8623.  
  8624.    Kermit presently has no built-in knowledge of the Caller ID
  8625.    capabilities or commands of the modems in its database.
  8626.    
  8627.    Since the variables can be accessed only after the call is answered,
  8628.    the only way to refuse a call is to answer it, inspect the variables,
  8629.    and then hang it up if desired.
  8630.    
  8631.    [ [509]Top ] [ [510]Contents ] [ [511]C-Kermit Home ] [ [512]Kermit
  8632.    Home ]
  8633.   __________________________________________________________________________
  8634.  
  8635. 12. TERMINAL CONNECTION
  8636.  
  8637.    Now that 7-bit connections are no longer the norm, the default
  8638.    terminal bytesize (also called "data size" or "word size") in C-Kermit
  8639.    8.0 is 8 bits, rather than 7 bits as it was in C-Kermit 7.0 and
  8640.    earlier:
  8641.    
  8642.    SET ESCAPE character
  8643.           This command, which specifies your CONNECT-mode escape
  8644.           character, allows you to specify any ASCII control character in
  8645.           a variety of formats. C-Kermit 8.0.201 now also lets you
  8646.           specify any 8-bit value, 128-255, as the escape character. In
  8647.           the SET ESCAPE command, you can type the 8-bit character
  8648.           literally or you can enter its numeric code. Here are examples
  8649.           that you can enter from a terminal or console that uses the ISO
  8650.           Latin-1 character set:
  8651.           
  8652.   C-Kermit> set escape ├
  8653.   C-Kermit> set escape 195
  8654.   C-Kermit> show escape
  8655.    Escape character: Code 195 (├): enabled
  8656.   C-Kermit>
  8657.  
  8658.           Both of these commands set the escape character value to 195
  8659.           (decimal), which happens to be uppercase letter A with Tilde in
  8660.           Latin-1. SHOW ESCAPE and SHOW TERMINAL show the value, as does
  8661.           the CONNECT message.
  8662.           
  8663.    SET TERMINAL AUTODOWNLOAD ERROR { STOP, CONTINUE }
  8664.           When Kermit has a terminal connection to another computer, and
  8665.           a file transfer is initiated automatically because a Kermit
  8666.           packet was received in CONNECT mode (i.e. in the terminal
  8667.           screen), this command tells what Kermit should do if the
  8668.           transfer fails. The default is to STOP, which leaves Kermit in
  8669.           command mode with its file-transfer display showing, so you can
  8670.           see that the transfer failed and why. If you SET TERMINAL
  8671.           AUTODOWNLOAD ERROR CONTINUE, this causes Kermit to return
  8672.           automatically to its terminal screen (i.e. resume its CONNECT
  8673.           session) as if the transfer had succeeded; this can be
  8674.           desirable if the entire session is under control of a
  8675.           host-based script.
  8676.           
  8677.    SET TERMINAL BYTESIZE { 7, 8 }
  8678.           The byte size to use during CONNECT and INPUT command
  8679.           execution, which can be more restrictive than the bytesize
  8680.           implied by the current PARITY setting, but not less
  8681.           restrictive. In C-Kermit 7.0 and earlier, the terminal bytesize
  8682.           was 7 by default to protect against the likelihood that parity
  8683.           was in use on the connection without the user's knowledge. When
  8684.           the terminal bytesize is 8 (as it is in C-Kermit 8.0 and
  8685.           later), the user will see garbage in this (increasingly
  8686.           unlikely) situation. Note that 8 data bits are required for
  8687.           most character sets other than ASCII: Latin-1, UTF-8, and so
  8688.           on.
  8689.           
  8690.    A new command has been added to produce timestamped session logs:
  8691.    
  8692.    SET TERMINAL SESSION-LOG TIMESTAMPED-TEXT
  8693.           Records the terminal session in text mode (like SET TERMINAL
  8694.           SESSION-LOG TEXT) but adds a timestamp at the beginning of each
  8695.           line. The timestamp format is hh:mm:ss.nnn, and indicates the
  8696.           time at which the first character of the line appeared.
  8697.           
  8698.    In most UNIX versions (those built with the select()-capable CONNECT
  8699.    module -- pretty much all the ones that have or could have TELNET
  8700.    included), an idle timeout feature has been added:
  8701.    
  8702.    SET TERMINAL IDLE-TIMEOUT number
  8703.           If the number is not 0, then Kermit is to take an action when
  8704.           the given amount of time passes with no activity during CONNECT
  8705.           mode. If the number is positive it is the maximum number of
  8706.           idle seconds; if number is negative it represents milliseconds
  8707.           (thousandths of seconds). If 0 is given as the number, there
  8708.           are no idle timeouts. Synonym: SET TERMINAL IDLE-LIMIT.
  8709.           
  8710.    SET TERMINAL IDLE-ACTION { RETURN, HANGUP, EXIT, OUTPUT [ string ] }
  8711.           The action to be taken upon an idle timeout in CONNECT mode.
  8712.           RETURN to the prompt, HANGUP the connection, EXIT from Kermit,
  8713.           or OUTPUT the given string (if no string is given, a NUL (ASCII
  8714.           0) character is sent).
  8715.           
  8716.    SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT }
  8717.           Actions that can be selected on Telnet connections only, that
  8718.           might be useful if idle limits are enforced by the Telnet
  8719.           server or in the TCP/IP protocol: TELNET-NOP sends a "NO
  8720.           Operation" (do-nothing) command, which causes no response from
  8721.           the server; TELNET-AYT sends an "Are You There" message to the
  8722.           server, which should make the server send back a message.
  8723.           Neither of these actions interferes with your remote session.
  8724.           
  8725.    SET TERMINAL IDLE-ACTION is useful for connections to hosts or
  8726.    services that automatically log you out after a certain amount of idle
  8727.    time, e.g.:
  8728.    
  8729.   set term idle-timeout 300
  8730.   set term idle-action output \32
  8731.  
  8732.    sends a space (as if you had pressed the space bar) every 300 seconds
  8733.    (five minutes) while there is no activity (32 is the ASCII code for
  8734.    space).
  8735.    
  8736.    When C-Kermit returns from CONNECT to command mode, the reason for the
  8737.    transition is given in a new variable, \v(cx_status):
  8738.    
  8739.       0  No CONNECT command given yet.
  8740.       1  User escaped back manually.
  8741.       2  A trigger string was encountered.
  8742.       3  IKSD entered server mode.
  8743.       4  Application Program Command received from host.
  8744.       5  Idle timeout.
  8745.       6  Telnet protocol error.
  8746.       7  Keystroke macro.
  8747.       8  Time limit exceeded.
  8748.     100  Internal error.
  8749.     101  Carrier required by not detected.
  8750.     102  I/O error on connection.
  8751.     103  Disconnected by host.
  8752.     104  Disconnected by user.
  8753.     105  Session limit exceeded.
  8754.     106  Rejected due to Telnet policy.
  8755.     107  Received kill signal.
  8756.    
  8757.    Values 100 and above indicate there is no connection.
  8758.    
  8759.    [ [513]Top ] [ [514]Contents ] [ [515]C-Kermit Home ] [ [516]Kermit
  8760.    Home ]
  8761.   __________________________________________________________________________
  8762.  
  8763. 13. CHARACTER SETS
  8764.  
  8765.    See the section on [517]file scanning above, and the section on
  8766.    character-set conversion in [518]FTP. Also:
  8767.    
  8768.      * True support for CP1252 (rather than treating it as Latin-1).
  8769.      * Proper handling of C1 values when converting ISO 8-bit text to
  8770.        UTF-8.
  8771.      * TYPE /CHARACTER-SET: /TRANSLATE-TO: allows specific translations.
  8772.      * The TRANSLATE command now works on multiple files.
  8773.      * K_CHARSET environment variable to set the file character-set.
  8774.      * SET TRANSFER TRANSLATION OFF.
  8775.      * FTP client character-set translation ([519]Section 3.7).
  8776.        
  8777.    [ [520]Top ] [ [521]Contents ] [ [522]C-Kermit Home ] [ [523]Kermit
  8778.    Home ]
  8779.   __________________________________________________________________________
  8780.  
  8781. 14. DIALOUT FROM TELNET TERMINAL SERVERS
  8782.  
  8783.    For years, C-Kermit has supported dialing out from Telnet modem
  8784.    servers (also called reverse terminal servers or access servers), but
  8785.    until now there was no way for Kermit to control the communication
  8786.    parameters (speed, parity, etc) on the serial port of the terminal
  8787.    server; it had to use whatever was there.
  8788.    
  8789.    But now, if you make a connection to a server that supports the Telnet
  8790.    Com Port Control Option, [524]RFC 2217, you have the same degree of
  8791.    control as you would have over a serial port on the computer where
  8792.    Kermit is running: SET SPEED, SET FLOW, SET PARITY, SET STOP-BITS,
  8793.    SHOW COMM, WAIT, SET CARRIER-WATCH, the modem-signal variables,
  8794.    sending Break, and so on, apply to the connection between the terminal
  8795.    server and the modem.
  8796.    
  8797.    For example, using a Cisco Access Server 2509, where specifying a TCP
  8798.    port in the 6000's selects a serial port that can be used for dialing
  8799.    out:
  8800.    
  8801.   set host xxx 6001      ; xxx is the IP hostname or address of the server
  8802.   (log in if necessary)  ; With a script or by hand
  8803.   set modem type usr     ; Tell Kermit what kind of modem it has
  8804.   set speed 57600        ; This affects the server's port
  8805.   set flow rts/cts       ; Ditto
  8806.   dial 7654321
  8807.  
  8808.    The modem server might or might not require a login sequence. It might
  8809.    also allow for automatic authentication, e.g. via Kerberos tickets.
  8810.    NOTE: If the modem server requires a login sequence, then REDIAL might
  8811.    not work as expected.
  8812.    
  8813.    When you have a Telnet Com Port connection, your SET SPEED and SET
  8814.    FLOW options change automatically to reflect the capabilities of the
  8815.    server, rather than those of your local computer.
  8816.    
  8817.    See the configuration manual for your server for additional
  8818.    information. For example, how to set up the server to drop the Telnet
  8819.    connection automatically when the telephone call is hung up (e.g.
  8820.    "autohangup" on Cisco models).
  8821.    
  8822.    For a Linux-based Telnet Com-Port server, click the Srdird link:
  8823.    
  8824.    [ [525]Top ] [ [526]Contents ] [ [527]Sredird ] [ [528]C-Kermit Home ]
  8825.    [ [529]Kermit Home ]
  8826.   __________________________________________________________________________
  8827.  
  8828. 15. COPING WITH BROKEN KERMIT PARTNERS
  8829.  
  8830.    There are lots of faulty Kermit protocol implementations out there,
  8831.    found mainly in 3rd-party products ranging from communications
  8832.    software packages to file-transfer functions imbedded within devices.
  8833.    This topic is covered [530]HERE for C-Kermit 7.0, but C-Kermit 8.0
  8834.    adds some additional tricks.
  8835.    
  8836.    SET ATTRIBUTE RECORD-FORMAT { ON, OFF }
  8837.           Allows control of the Kermit's Record-Format attribute. Set
  8838.           this to OFF in case incoming file are refused due to unknown or
  8839.           invalid record formats if you want to accept the file anyway.
  8840.           
  8841.    SET SEND I-PACKETS { ON, OFF }
  8842.           A Kermit server is supposed to accept I-packets; this is how
  8843.           the client lets the server know its capabilities and
  8844.           preferences before sending a command. Apparently there is at
  8845.           least one Kermit server implementation that does not accept
  8846.           I-packets, and does not properly respond with an Error packet
  8847.           if it gets one. To get around such situations in C-Kermit 8.0,
  8848.           you can use SET SEND I-PACKETS OFF to inhibit the sending of I
  8849.           packets. In this case, the client must be able to adjust to the
  8850.           server's configuration, rather than the other way around as we
  8851.           are used to.
  8852.           
  8853.    SET PROTOCOL KERMIT {} {} {}
  8854.           C-Kermit 6.0 and later automatically send "autoupload" and
  8855.           "autodownload" commands when in local mode and you give a file
  8856.           transfer command. For example, if you tell kermit to "send
  8857.           oofa.txt", Kermit sends "kermit -r" and a carriage return, in
  8858.           case you had forgotten to start Kermit on the far end and told
  8859.           it to receive a file. If a Kermit program had already been
  8860.           started on the far end, it should harmlessly absorb this
  8861.           string. However, some Kermit programs violate the Kermit
  8862.           protocol definition and treat such strings as Kermit packets
  8863.           even though they are not. In such cases, give this command to
  8864.           set the Kermit protocol autoupload and download strings to
  8865.           nothing, which tells Kermit not to send them. (This is not a
  8866.           new feature, but it was not previously included in the "Coping"
  8867.           section of the documentation.)
  8868.           
  8869.    [ [531]Top ] [ [532]Contents ] [ [533]C-Kermit Home ] [ [534]Kermit
  8870.    Home ]
  8871.   __________________________________________________________________________
  8872.  
  8873. 16. NEW COMMAND-LINE OPTIONS
  8874.  
  8875.    kermit -h Now prints a complete listing of its command-line options,
  8876.    rather than an abbreviated list squeezed into a 24x80 space.
  8877.    
  8878.    -dd              Debug, like -d but adds timestamps
  8879.    --version  Shows C-Kermit version number.
  8880.    --noperms  Equivalent to SET ATTRIBUTE PROTECTION OFF.
  8881.    
  8882.    Kermit now accepts a selection of URLs (Universal Resource Locators)
  8883.    as its first command-line argument. These are:
  8884.    
  8885.    telnet:hostname
  8886.           Makes a Telnet connection to the given host (IP hostname or
  8887.           address).
  8888.           
  8889.    ftp://[user[:password]@]hostname[/path...]
  8890.           Makes an FTP connection to the given host (IP hostname or
  8891.           address). If a username is given, Kermit tries to log you in;
  8892.           if a password is given, it is used; if not, you are prompted
  8893.           for one. If no username is given, an anonymous login is
  8894.           performed. If a pathname is included, Kermit tries to GET the
  8895.           given file. See [535]Section 3.1.3 for details.
  8896.           
  8897.    ftps://[user[:password]@]hostname[/path...]
  8898.           Makes a secure FTP connection over SSL.
  8899.           
  8900.    telnets://[user[:password]@]hostname
  8901.           Makes a secure Telnet connection over SSL.
  8902.           
  8903.    kermit://[user[:password]@]hostname[/path...]
  8904.           Makes a connection to an [536]Internet Kermit Server.
  8905.           
  8906.    http://[user[:password]@]hostname[/path...]
  8907.           Makes a connection to Web server.
  8908.           
  8909.    https://[user[:password]@]hostname[/path...]
  8910.           Makes a connection to secure Web server.
  8911.           
  8912.    [ [537]Top ] [ [538]Contents ] [ [539]C-Kermit Home ] [ [540]Kermit
  8913.    Home ]
  8914.   __________________________________________________________________________
  8915.  
  8916. 17. LOGS
  8917.  
  8918.    In C-Kermit 8.0, we make an effort to keep passwords out of the debug
  8919.    log. This can never be 100% effective, but it's far better than
  8920.    before, when there were no precautions at all. Whenever Kermit knows
  8921.    it's prompting for, parsing, or transmitting a password, it
  8922.    temporarily turns off logging and then turns it back on afterwards.
  8923.    This keeps the debug log password-free in most common cases, but there
  8924.    can be no guarantees.
  8925.    
  8926.    As noted elsewhere, the new "-dd" command-line option selects a
  8927.    timestamped debug log (equivalent to "set debug timestamps on", "log
  8928.    debug debug.log").
  8929.    
  8930.    C-Kermit 8.0 also supports a new timestamped session log via "set
  8931.    session-log timestamped-text", "log session".
  8932.    
  8933.    There have been requests for other kinds of logs, for example a
  8934.    command log. These might be added at some point. One person wanted to
  8935.    be able to log commands with timestamps, but only commands issued at
  8936.    the prompt, not commands from files or macros, and also wanted a
  8937.    header line at the beginning showing the date, user, and host. This
  8938.    can be done as follows:
  8939.    
  8940.   .filename := \v(home)commands.log  ; (for example)
  8941.   fopen /write \%c \m(filename)
  8942.   if success {
  8943.       fwrite /line \%c \v(date): User=\v(user) Host=\v(host)
  8944.       fclose \%c
  8945.       set debug timestamps on
  8946.       log debug {| grep "CMD(P)" >> \m(filename)} append
  8947.   }
  8948.  
  8949.    [ [541]Top ] [ [542]Contents ] [ [543]C-Kermit Home ] [ [544]Kermit
  8950.    Home ]
  8951.      _________________________________________________________________
  8952.    
  8953.    C-Kermit 8.0 Update Notes / [545]The Kermit Project / Columbia
  8954.    University / 13 Feb 2002
  8955.  
  8956. References
  8957.  
  8958.    1. http://www.columbia.edu/kermit/ckermit80.html#contents
  8959.    2. http://www.columbia.edu/kermit/ckermit.html
  8960.    3. http://www.columbia.edu/kermit/index.html
  8961.    4. http://www.columbia.edu/kermit/ckermit80.html
  8962.    5. mailto:kermit-support@columbia.edu
  8963.    6. http://www.columbia.edu/kermit/
  8964.    7. http://www.kermit-project.org/
  8965.    8. http://www.columbia.nyc.ny.us/kermit/
  8966.    9. ftp://kermit.columbia.edu/kermit/f/COPYING.TXT
  8967.   10. ftp://kermit.columbia.edu/kermit/f/ckcmai.c
  8968.   11. http://www.columbia.edu/kermit/ckermit80.html#xv
  8969.   12. http://www.columbia.edu/kermit/ck60manual.html
  8970.   13. http://www.columbia.edu/kermit/ckermit70.html
  8971.   14. ftp://kermit.columbia.edu/kermit/f/ckermit70.txt
  8972.   15. http://www.columbia.edu/kermit/ckututor.html
  8973.   16. ftp://kermit.columbia.edu/kermit/f/ckuker.nr
  8974.   17. http://www.columbia.edu/kermit/security80.html
  8975.   18. http://www.columbia.edu/kermit/telnet80.html
  8976.   19. http://www.columbia.edu/kermit/ftpscripts.html
  8977.   20. http://www.columbia.edu/kermit/ckcbwr.html
  8978.   21. ftp://kermit.columbia.edu/kermit/f/ckcbwr.txt
  8979.   22. http://www.columbia.edu/kermit/ckubwr.html
  8980.   23. ftp://kermit.columbia.edu/kermit/f/ckubwr.txt
  8981.   24. http://www.columbia.edu/kermit/ckvbwr.html
  8982.   25. ftp://kermit.columbia.edu/kermit/f/ckvbwr.txt
  8983.   26. http://www.columbia.edu/kermit/ckuins.html
  8984.   27. ftp://kermit.columbia.edu/kermit/f/ckuins.txt
  8985.   28. http://www.columbia.edu/kermit/ckvins.html
  8986.   29. ftp://kermit.columbia.edu/kermit/f/ckvins.txt
  8987.   30. http://www.columbia.edu/kermit/ckccfg.html
  8988.   31. ftp://kermit.columbia.edu/kermit/f/ckccfg.txt
  8989.   32. http://www.columbia.edu/kermit/ckcplm.html
  8990.   33. ftp://kermit.columbia.edu/kermit/f/ckcplm.txt
  8991.   34. http://www.columbia.edu/kermit/iksd.html
  8992.   35. http://www.columbia.edu/kermit/skermit.html
  8993.   36. http://www.columbia.edu/kermit/ckermit80.html#top
  8994.   37. http://www.columbia.edu/kermit/ckermit.html
  8995.   38. http://www.columbia.edu/kermit/index.html
  8996.   39. http://www.columbia.edu/kermit/ckermit80.html#x0
  8997.   40. http://www.columbia.edu/kermit/ckermit80.html#x1
  8998.   41. http://www.columbia.edu/kermit/ckermit80.html#x2
  8999.   42. http://www.columbia.edu/kermit/ckermit80.html#x2.1
  9000.   43. http://www.columbia.edu/kermit/ckermit80.html#x2.2
  9001.   44. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1
  9002.   45. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2
  9003.   46. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3
  9004.   47. http://www.columbia.edu/kermit/ckermit80.html#x2.2.4
  9005.   48. http://www.columbia.edu/kermit/ckermit80.html#x2.2.5
  9006.   49. http://www.columbia.edu/kermit/ckermit80.html#x2.2.6
  9007.   50. http://www.columbia.edu/kermit/ckermit80.html#x3
  9008.   51. http://www.columbia.edu/kermit/ckermit80.html#x3.1
  9009.   52. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1
  9010.   53. http://www.columbia.edu/kermit/ckermit80.html#x3.1.2
  9011.   54. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9012.   55. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
  9013.   56. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9014.   57. http://www.columbia.edu/kermit/ckermit80.html#x3.3
  9015.   58. http://www.columbia.edu/kermit/ckermit80.html#x3.4
  9016.   59. http://www.columbia.edu/kermit/ckermit80.html#x3.5
  9017.   60. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1
  9018.   61. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
  9019.   62. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3
  9020.   63. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9021.   64. http://www.columbia.edu/kermit/ckermit80.html#x3.6.1
  9022.   65. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
  9023.   66. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3
  9024.   67. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9025.   68. http://www.columbia.edu/kermit/ckermit80.html#x3.7.1
  9026.   69. http://www.columbia.edu/kermit/ckermit80.html#x3.7.2
  9027.   70. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9028.   71. http://www.columbia.edu/kermit/ckermit80.html#x3.9
  9029.   72. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9030.   73. http://www.columbia.edu/kermit/ckermit80.html#x3.10.1
  9031.   74. http://www.columbia.edu/kermit/ckermit80.html#x3.10.2
  9032.   75. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  9033.   76. http://www.columbia.edu/kermit/ckermit80.html#x4
  9034.   77. http://www.columbia.edu/kermit/ckermit80.html#x5
  9035.   78. http://www.columbia.edu/kermit/ckermit80.html#x6
  9036.   79. http://www.columbia.edu/kermit/ckermit80.html#x6.1
  9037.   80. http://www.columbia.edu/kermit/ckermit80.html#x6.2
  9038.   81. http://www.columbia.edu/kermit/ckermit80.html#x6.3
  9039.   82. http://www.columbia.edu/kermit/ckermit80.html#x6.4
  9040.   83. http://www.columbia.edu/kermit/ckermit80.html#x6.5
  9041.   84. http://www.columbia.edu/kermit/ckermit80.html#x6.6
  9042.   85. http://www.columbia.edu/kermit/ckermit80.html#x7
  9043.   86. http://www.columbia.edu/kermit/ckermit80.html#x8
  9044.   87. http://www.columbia.edu/kermit/ckermit80.html#x8.1
  9045.   88. http://www.columbia.edu/kermit/ckermit80.html#x8.2
  9046.   89. http://www.columbia.edu/kermit/ckermit80.html#x8.3
  9047.   90. http://www.columbia.edu/kermit/ckermit80.html#x8.4
  9048.   91. http://www.columbia.edu/kermit/ckermit80.html#x8.5
  9049.   92. http://www.columbia.edu/kermit/ckermit80.html#x8.6
  9050.   93. http://www.columbia.edu/kermit/ckermit80.html#x8.7
  9051.   94. http://www.columbia.edu/kermit/ckermit80.html#x8.8
  9052.   95. http://www.columbia.edu/kermit/ckermit80.html#x8.9
  9053.   96. http://www.columbia.edu/kermit/ckermit80.html#x8.10
  9054.   97. http://www.columbia.edu/kermit/ckermit80.html#x8.11
  9055.   98. http://www.columbia.edu/kermit/ckermit80.html#x8.12
  9056.   99. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9057.  100. http://www.columbia.edu/kermit/ckermit80.html#x8.14
  9058.  101. http://www.columbia.edu/kermit/ckermit80.html#x9
  9059.  102. http://www.columbia.edu/kermit/ckermit80.html#x9.1
  9060.  103. http://www.columbia.edu/kermit/ckermit80.html#x9.2
  9061.  104. http://www.columbia.edu/kermit/ckermit80.html#x9.3
  9062.  105. http://www.columbia.edu/kermit/ckermit80.html#x9.4
  9063.  106. http://www.columbia.edu/kermit/ckermit80.html#x9.5
  9064.  107. http://www.columbia.edu/kermit/ckermit80.html#x9.6
  9065.  108. http://www.columbia.edu/kermit/ckermit80.html#x9.7
  9066.  109. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9067.  110. http://www.columbia.edu/kermit/ckermit80.html#x9.9
  9068.  111. http://www.columbia.edu/kermit/ckermit80.html#x9.10
  9069.  112. http://www.columbia.edu/kermit/ckermit80.html#x9.11
  9070.  113. http://www.columbia.edu/kermit/ckermit80.html#x10
  9071.  114. http://www.columbia.edu/kermit/ckermit80.html#x11
  9072.  115. http://www.columbia.edu/kermit/ckermit80.html#x12
  9073.  116. http://www.columbia.edu/kermit/ckermit80.html#x13
  9074.  117. http://www.columbia.edu/kermit/ckermit80.html#x14
  9075.  118. http://www.columbia.edu/kermit/ckermit80.html#x15
  9076.  119. http://www.columbia.edu/kermit/ckermit80.html#x16
  9077.  120. http://www.columbia.edu/kermit/ckermit80.html#x17
  9078.  121. http://www.columbia.edu/kermit/ckermit80.html#top
  9079.  122. http://www.columbia.edu/kermit/ckermit.html
  9080.  123. http://www.columbia.edu/kermit/index.html
  9081.  124. http://www.columbia.edu/kermit/ckuins.html#x5
  9082.  125. http://www.columbia.edu/kermit/ckuins.html
  9083.  126. http://www.columbia.edu/kermit/ckermit80.html#x5
  9084.  127. http://www.columbia.edu/kermit/ckermit80.html#x2.2
  9085.  128. http://www.columbia.edu/kermit/ckermit80.html#contents
  9086.  129. http://www.columbia.edu/kermit/ckermit80.html#x15
  9087.  130. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9088.  131. http://www.columbia.edu/kermit/ckermit80.html#ftpdates
  9089.  132. http://www.columbia.edu/kermit/ckermit80.html#ftpcheck
  9090.  133. http://www.columbia.edu/kermit/ckermit80.html#ftpnamelist
  9091.  134. http://www.columbia.edu/kermit/ckermit80.html#srvrename
  9092.  135. http://www.columbia.edu/kermit/ckermit80.html#ftpvdir
  9093.  136. http://www.columbia.edu/kermit/ckermit80.html#setftptype
  9094.  137. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9095.  138. http://www.columbia.edu/kermit/ckermit80.html#x15
  9096.  139. http://www.columbia.edu/kermit/ckermit80.html#x8.7
  9097.  140. http://www.columbia.edu/kermit/ckermit80.html#x2.1
  9098.  141. http://www.columbia.edu/kermit/ckermit80.html#x2.2
  9099.  142. http://www.columbia.edu/kermit/ckermit80.html#x8.14
  9100.  143. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9101.  144. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9102.  145. http://www.columbia.edu/kermit/ckututor.html
  9103.  146. http://www.columbia.edu/kermit/ckuins.html
  9104.  147. http://www.columbia.edu/kermit/skermit.html
  9105.  148. http://www.columbia.edu/kermit/ckermit80.html#setlocus
  9106.  149. http://www.columbia.edu/kermit/ckermit80.html#lcommands
  9107.  150. http://www.columbia.edu/kermit/ckermit80.html#ftpuser
  9108.  151. http://www.columbia.edu/kermit/ckermit80.html#showvar
  9109.  152. http://www.columbia.edu/kermit/ckermit80.html#callerid
  9110.  153. http://www.columbia.edu/kermit/ckermit80.html#x6.6
  9111.  154. http://www.columbia.edu/kermit/ckermit80.html#x0
  9112.  155. http://www.columbia.edu/kermit/ckermit80.html#top
  9113.  156. http://www.columbia.edu/kermit/ckermit80.html#contents
  9114.  157. http://www.columbia.edu/kermit/ckermit.html
  9115.  158. http://www.columbia.edu/kermit/index.html
  9116.  159. http://www.columbia.edu/kermit/ckermit80.html#top
  9117.  160. http://www.columbia.edu/kermit/ckermit80.html#contents
  9118.  161. http://www.columbia.edu/kermit/ckermit.html
  9119.  162. http://www.columbia.edu/kermit/index.html
  9120.  163. http://www.columbia.edu/kermit/skermit.html
  9121.  164. http://www.columbia.edu/kermit/skermit.html
  9122.  165. http://www.columbia.edu/kermit/sshclient.html
  9123.  166. http://www.columbia.edu/kermit/ckermit80.html#x3
  9124.  167. ftp://ftp.isi.edu/in-notes/rfc1738.txt
  9125.  168. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2
  9126.  169. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1
  9127.  170. ftp://ftp.isi.edu/in-notes/rfc2396.txt
  9128.  171. ftp://ftp.isi.edu/in-notes/rfc2616.txt
  9129.  172. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3
  9130.  173. ftp://ftp.isi.edu/in-notes/rfc2616.txt
  9131.  174. http://www.columbia.edu/kermit/ckermit80.html#x8.13.7
  9132.  175. http://www.columbia.edu/kermit/security80.html#x5.4
  9133.  176. http://www.columbia.edu/kermit/security80.html#x15
  9134.  177. http://www.columbia.edu/kermit/security80.html#x6.2
  9135.  178. http://www.columbia.edu/kermit/security80.html
  9136.  179. http://www.columbia.edu/kermit/ckermit80.html#x16
  9137.  180. http://www.columbia.edu/kermit/ckermit80.html#top
  9138.  181. http://www.columbia.edu/kermit/ckermit80.html#contents
  9139.  182. http://www.columbia.edu/kermit/ckermit.html
  9140.  183. http://www.columbia.edu/kermit/index.html
  9141.  184. http://www.columbia.edu/kermit/security80.html
  9142.  185. http://www.columbia.edu/kermit/ftpd.html
  9143.  186. http://www.columbia.edu/kermit/ckcsets.html
  9144.  187. http://www.columbia.edu/kermit/unicode.html
  9145.  188. http://www.columbia.edu/kermit/ckermit70.html#x1.5.4
  9146.  189. http://www.columbia.edu/kermit/case10.html
  9147.  190. http://www.columbia.edu/kermit/ckermit80.html#x4
  9148.  191. http://www.columbia.edu/kermit/ftpscripts.html
  9149.  192. http://www.columbia.edu/kermit/ckermit80.html#top
  9150.  193. http://www.columbia.edu/kermit/ckermit80.html#contents
  9151.  194. http://www.columbia.edu/kermit/ftpclient.html
  9152.  195. http://www.columbia.edu/kermit/ftpscripts.html
  9153.  196. http://www.columbia.edu/kermit/ckermit.html
  9154.  197. http://www.columbia.edu/kermit/index.html
  9155.  198. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1
  9156.  199. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9157.  200. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
  9158.  201. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9159.  202. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9160.  203. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9161.  204. http://www.columbia.edu/kermit/ckermit80.html#x3.5
  9162.  205. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9163.  206. http://www.columbia.edu/kermit/ftpscript.html
  9164.  207. http://www.columbia.edu/kermit/ck60manual.html
  9165.  208. http://www.columbia.edu/kermit/ckermit80.html#ftpautolog
  9166.  209. http://www.columbia.edu/kermit/ckermit80.html#ftpuser
  9167.  210. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9168.  211. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9169.  212. http://www.columbia.edu/kermit/ckermit80.html#top
  9170.  213. http://www.columbia.edu/kermit/ckermit80.html#contents
  9171.  214. http://www.columbia.edu/kermit/ckermit.html
  9172.  215. http://www.columbia.edu/kermit/index.html
  9173.  216. http://www.columbia.edu/kermit/ckermit80.html#top
  9174.  217. http://www.columbia.edu/kermit/ckermit80.html#contents
  9175.  218. http://www.columbia.edu/kermit/ckermit.html
  9176.  219. http://www.columbia.edu/kermit/index.html
  9177.  220. http://www.columbia.edu/kermit/ck60manual.html
  9178.  221. http://www.columbia.edu/kermit/ckermit70.html#x4.17
  9179.  222. http://www.columbia.edu/kermit/ckermit70.html
  9180.  223. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9181.  224. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
  9182.  225. http://www.columbia.edu/kermit/security80.html
  9183.  226. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9184.  227. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9185.  228. http://www.columbia.edu/kermit/ckermit80.html#permswitch
  9186.  229. http://www.columbia.edu/kermit/ckermit80.html#ftpchmod
  9187.  230. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
  9188.  231. http://www.columbia.edu/kermit/ckermit80.html#x4
  9189.  232. http://www.columbia.edu/kermit/ckermit80.html#top
  9190.  233. http://www.columbia.edu/kermit/ckermit80.html#contents
  9191.  234. http://www.columbia.edu/kermit/ckermit.html
  9192.  235. http://www.columbia.edu/kermit/index.html
  9193.  236. http://www.columbia.edu/kermit/ckermit80.html#x7
  9194.  237. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9195.  238. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9196.  239. http://www.columbia.edu/kermit/ck60manual.html
  9197.  240. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9198.  241. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9199.  242. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9200.  243. http://www.columbia.edu/kermit/ckermit80.html#setftptype
  9201.  244. http://www.columbia.edu/kermit/ckermit80.html#top
  9202.  245. http://www.columbia.edu/kermit/ckermit80.html#contents
  9203.  246. http://www.columbia.edu/kermit/ckermit.html
  9204.  247. http://www.columbia.edu/kermit/index.html
  9205.  248. http://www.columbia.edu/kermit/ckermit70.html#x4.9
  9206.  249. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1
  9207.  250. http://www.columbia.edu/kermit/ckermit80.html#erroraction
  9208.  251. http://www.columbia.edu/kermit/ckermit70.html#x1.5
  9209.  252. http://www.columbia.edu/kermit/ckermit70.html#x4.7
  9210.  253. http://www.columbia.edu/kermit/ckermit70.html#x1.6
  9211.  254. http://www.columbia.edu/kermit/ckermit70.html#x1.5.4
  9212.  255. http://www.columbia.edu/kermit/ckermit70.html
  9213.  256. http://www.columbia.edu/kermit/ckermit80.html#x4
  9214.  257. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9215.  258. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
  9216.  259. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9217.  260. http://www.columbia.edu/kermit/ckermit80.html#erroraction
  9218.  261. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
  9219.  262. http://www.columbia.edu/kermit/ckermit80.html#erroraction
  9220.  263. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  9221.  264. http://www.columbia.edu/kermit/ckermit80.html#ftpperms
  9222.  265. http://www.columbia.edu/kermit/ckermit80.html#ftpunique
  9223.  266. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  9224.  267. http://www.columbia.edu/kermit/ckermit80.html#note_utc
  9225.  268. http://www.columbia.edu/kermit/ckermit80.html#note_date
  9226.  269. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9227.  270. http://www.boulder.nist.gov/timefreq/faq/faq.htm#10:
  9228.  271. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9229.  272. http://www.columbia.edu/kermit/ckermit80.html#top
  9230.  273. http://www.columbia.edu/kermit/ckermit80.html#contents
  9231.  274. http://www.columbia.edu/kermit/ckermit.html
  9232.  275. http://www.columbia.edu/kermit/index.html
  9233.  276. http://www.columbia.edu/kermit/ckermit70.html#x4.3
  9234.  277. http://www.columbia.edu/kermit/ckermit70.html
  9235.  278. http://www.columbia.edu/kermit/ckermit80.html#x5
  9236.  279. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3
  9237.  280. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  9238.  281. http://www.columbia.edu/kermit/ckermit70.html#x4.1
  9239.  282. http://www.columbia.edu/kermit/ckermit70.html#x4.2.2
  9240.  283. http://www.columbia.edu/kermit/ckermit70.html#x1.5.4
  9241.  284. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
  9242.  285. http://www.columbia.edu/kermit/ckermit80.html#srvrename
  9243.  286. http://www.columbia.edu/kermit/ckermit70.html#x4.1
  9244.  287. http://www.columbia.edu/kermit/ckermit70.html
  9245.  288. http://www.columbia.edu/kermit/ck60manual.html
  9246.  289. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  9247.  290. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3
  9248.  291. http://www.proftpd.net/
  9249.  292. http://www.columbia.edu/kermit/ckermit80.html#top
  9250.  293. http://www.columbia.edu/kermit/ckermit80.html#contents
  9251.  294. http://www.columbia.edu/kermit/ckermit.html
  9252.  295. http://www.columbia.edu/kermit/index.html
  9253.  296. http://www.columbia.edu/kermit/ck60manual.html
  9254.  297. http://www.columbia.edu/kermit/ckcsets.html
  9255.  298. http://www.columbia.edu/kermit/unicode.html
  9256.  299. http://www.columbia.edu/kermit/ckcsets.html
  9257.  300. http://www.columbia.edu/kermit/ckcsets.html
  9258.  301. http://www.columbia.edu/kermit/ckermit80.html#x4
  9259.  302. http://www.columbia.edu/kermit/utf8.html
  9260.  303. http://www.columbia.edu/kermit/ckcsets.html
  9261.  304. http://www.columbia.edu/kermit/ckermit80.html#x4
  9262.  305. ftp://ftp.isi.edu/in-notes/rfc2640.txt
  9263.  306. http://www.columbia.edu/kermit/ckermit80.html#top
  9264.  307. http://www.columbia.edu/kermit/ckermit80.html#contents
  9265.  308. http://www.columbia.edu/kermit/ckermit.html
  9266.  309. http://www.columbia.edu/kermit/index.html
  9267.  310. http://www.columbia.edu/kermit/ckermit80.html#top
  9268.  311. http://www.columbia.edu/kermit/ckermit80.html#contents
  9269.  312. http://www.columbia.edu/kermit/ckermit.html
  9270.  313. http://www.columbia.edu/kermit/index.html
  9271.  314. http://www.columbia.edu/kermit/ckermit80.html#top
  9272.  315. http://www.columbia.edu/kermit/ckermit80.html#contents
  9273.  316. http://www.columbia.edu/kermit/ckermit.html
  9274.  317. http://www.columbia.edu/kermit/index.html
  9275.  318. http://www.columbia.edu/kermit/ftpscripts.html
  9276.  319. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9277.  320. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9278.  321. ftp://ftp.isi.edu/in-notes/rfc959.txt
  9279.  322. http://www.columbia.edu/kermit/ckscripts.html
  9280.  323. http://www.columbia.edu/kermit/ftpscript.html
  9281.  324. http://www.columbia.edu/kermit/ckermit80.html#top
  9282.  325. http://www.columbia.edu/kermit/ckermit80.html#contents
  9283.  326. http://www.columbia.edu/kermit/ckermit.html
  9284.  327. http://www.columbia.edu/kermit/index.html
  9285.  328. http://www.columbia.edu/kermit/ckermit80.html#top
  9286.  329. http://www.columbia.edu/kermit/ckermit80.html#contents
  9287.  330. http://www.columbia.edu/kermit/ckermit.html
  9288.  331. http://www.columbia.edu/kermit/index.html
  9289.  332. http://www.columbia.edu/kermit/ckermit80.html#x3
  9290.  333. http://www.columbia.edu/kermit/ckermit80.html#ucs2
  9291.  334. http://www.columbia.edu/kermit/ckermit80.html#top
  9292.  335. http://www.columbia.edu/kermit/ckermit80.html#contents
  9293.  336. http://www.columbia.edu/kermit/ckermit.html
  9294.  337. http://www.columbia.edu/kermit/index.html
  9295.  338. http://www.columbia.edu/kermit/ckermit80.html#top
  9296.  339. http://www.columbia.edu/kermit/ckermit80.html#contents
  9297.  340. http://www.columbia.edu/kermit/ckermit.html
  9298.  341. http://www.columbia.edu/kermit/index.html
  9299.  342. http://www.columbia.edu/kermit/ck60manual.html
  9300.  343. http://www.columbia.edu/kermit/ckermit80.html#top
  9301.  344. http://www.columbia.edu/kermit/ckermit80.html#contents
  9302.  345. http://www.columbia.edu/kermit/ckermit.html
  9303.  346. http://www.columbia.edu/kermit/index.html
  9304.  347. http://www.columbia.edu/kermit/ckermit80.html#x4
  9305.  348. http://www.columbia.edu/kermit/ckermit80.html#x4
  9306.  349. http://www.columbia.edu/kermit/ckermit80.html#x8.12
  9307.  350. http://www.columbia.edu/kermit/ckermit80.html#x8.1
  9308.  351. http://www.columbia.edu/kermit/ckermit80.html#x12
  9309.  352. http://www.columbia.edu/kermit/ckermit80.html#x8.12
  9310.  353. http://www.columbia.edu/kermit/ckermit80.html#top
  9311.  354. http://www.columbia.edu/kermit/ckermit80.html#contents
  9312.  355. http://www.columbia.edu/kermit/ckermit.html
  9313.  356. http://www.columbia.edu/kermit/index.html
  9314.  357. http://www.columbia.edu/kermit/ckermit80.html#x8.14
  9315.  358. http://www.columbia.edu/kermit/ckermit80.html#top
  9316.  359. http://www.columbia.edu/kermit/ckermit80.html#contents
  9317.  360. http://www.columbia.edu/kermit/ckermit.html
  9318.  361. http://www.columbia.edu/kermit/index.html
  9319.  362. http://www.columbia.edu/kermit/ckermit80.html#x9
  9320.  363. http://www.columbia.edu/kermit/ckermit80.html#top
  9321.  364. http://www.columbia.edu/kermit/ckermit80.html#contents
  9322.  365. http://www.columbia.edu/kermit/ckermit.html
  9323.  366. http://www.columbia.edu/kermit/index.html
  9324.  367. http://www.columbia.edu/kermit/ckermit80.html#x8.6
  9325.  368. http://www.columbia.edu/kermit/ckermit80.html#top
  9326.  369. http://www.columbia.edu/kermit/ckermit80.html#contents
  9327.  370. http://www.columbia.edu/kermit/ckermit.html
  9328.  371. http://www.columbia.edu/kermit/index.html
  9329.  372. http://www.columbia.edu/kermit/ckermit80.html#top
  9330.  373. http://www.columbia.edu/kermit/ckermit80.html#contents
  9331.  374. http://www.columbia.edu/kermit/ckermit.html
  9332.  375. http://www.columbia.edu/kermit/index.html
  9333.  376. http://www.columbia.edu/kermit/ckermit80.html#top
  9334.  377. http://www.columbia.edu/kermit/ckermit80.html#contents
  9335.  378. http://www.columbia.edu/kermit/ckermit.html
  9336.  379. http://www.columbia.edu/kermit/index.html
  9337.  380. http://www.columbia.edu/kermit/ckermit80.html#fjoin
  9338.  381. http://www.columbia.edu/kermit/ckermit80.html#fsplit
  9339.  382. http://www.columbia.edu/kermit/ckermit80.html#x8.10
  9340.  383. http://www.columbia.edu/kermit/ckermit80.html#top
  9341.  384. http://www.columbia.edu/kermit/ckermit80.html#contents
  9342.  385. http://www.columbia.edu/kermit/ckermit.html
  9343.  386. http://www.columbia.edu/kermit/index.html
  9344.  387. http://www.columbia.edu/kermit/ckermit80.html#x9
  9345.  388. http://www.columbia.edu/kermit/ckermit80.html#x9
  9346.  389. http://www.columbia.edu/kermit/ckermit80.html#x9
  9347.  390. http://www.columbia.edu/kermit/ckermit80.html#x3
  9348.  391. http://www.columbia.edu/kermit/ckermit80.html#x3
  9349.  392. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9350.  393. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9351.  394. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9352.  395. http://www.columbia.edu/kermit/ckermit80.html#x3
  9353.  396. http://www.columbia.edu/kermit/ckermit80.html#x3
  9354.  397. http://www.columbia.edu/kermit/ckermit80.html#x3
  9355.  398. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9356.  399. http://www.columbia.edu/kermit/ckermit80.html#x3
  9357.  400. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9358.  401. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9359.  402. http://www.columbia.edu/kermit/ckermit80.html#x9
  9360.  403. http://www.columbia.edu/kermit/ckermit80.html#x8.7.4
  9361.  404. http://www.columbia.edu/kermit/ckermit80.html#top
  9362.  405. http://www.columbia.edu/kermit/ckermit80.html#contents
  9363.  406. http://www.columbia.edu/kermit/ckermit.html
  9364.  407. http://www.columbia.edu/kermit/index.html
  9365.  408. http://www.columbia.edu/kermit/ckermit80.html#top
  9366.  409. http://www.columbia.edu/kermit/ckermit80.html#contents
  9367.  410. http://www.columbia.edu/kermit/ckermit.html
  9368.  411. http://www.columbia.edu/kermit/index.html
  9369.  412. http://www.columbia.edu/kermit/ckermit80.html#top
  9370.  413. http://www.columbia.edu/kermit/ckermit80.html#contents
  9371.  414. http://www.columbia.edu/kermit/ckermit.html
  9372.  415. http://www.columbia.edu/kermit/index.html
  9373.  416. http://www.columbia.edu/kermit/ckermit80.html#x8.7
  9374.  417. http://www.columbia.edu/kermit/ckermit80.html#top
  9375.  418. http://www.columbia.edu/kermit/ckermit80.html#contents
  9376.  419. http://www.columbia.edu/kermit/ckermit.html
  9377.  420. http://www.columbia.edu/kermit/index.html
  9378.  421. http://www.columbia.edu/kermit/ckermit80.html#scriptedit
  9379.  422. http://www.columbia.edu/kermit/ckermit80.html#top
  9380.  423. http://www.columbia.edu/kermit/ckermit80.html#contents
  9381.  424. http://www.columbia.edu/kermit/ckermit.html
  9382.  425. http://www.columbia.edu/kermit/index.html
  9383.  426. http://www.columbia.edu/kermit/ckermit80.html#top
  9384.  427. http://www.columbia.edu/kermit/ckermit80.html#contents
  9385.  428. http://www.columbia.edu/kermit/ckermit.html
  9386.  429. http://www.columbia.edu/kermit/index.html
  9387.  430. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  9388.  431. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  9389.  432. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  9390.  433. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  9391.  434. http://www.columbia.edu/kermit/ckermit80.html#top
  9392.  435. http://www.columbia.edu/kermit/ckermit80.html#contents
  9393.  436. http://www.columbia.edu/kermit/ckermit.html
  9394.  437. http://www.columbia.edu/kermit/index.html
  9395.  438. http://www.columbia.edu/kermit/ckermit80.html#x8.1
  9396.  439. http://www.columbia.edu/kermit/ckermit80.html#top
  9397.  440. http://www.columbia.edu/kermit/ckermit80.html#contents
  9398.  441. http://www.columbia.edu/kermit/ckermit.html
  9399.  442. http://www.columbia.edu/kermit/index.html
  9400.  443. http://www.columbia.edu/kermit/ckermit80.html#x8.2
  9401.  444. http://www.columbia.edu/kermit/ckermit80.html#top
  9402.  445. http://www.columbia.edu/kermit/ckermit80.html#contents
  9403.  446. http://www.columbia.edu/kermit/ckermit.html
  9404.  447. http://www.columbia.edu/kermit/index.html
  9405.  448. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9406.  449. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9407.  450. http://www.columbia.edu/kermit/ckermit80.html#x8.2
  9408.  451. http://www.columbia.edu/kermit/ckermit80.html#top
  9409.  452. http://www.columbia.edu/kermit/ckermit80.html#contents
  9410.  453. http://www.columbia.edu/kermit/ckermit.html
  9411.  454. http://www.columbia.edu/kermit/index.html
  9412.  455. http://www.columbia.edu/kermit/ckermit80.html#top
  9413.  456. http://www.columbia.edu/kermit/ckermit80.html#contents
  9414.  457. http://www.columbia.edu/kermit/ckermit.html
  9415.  458. http://www.columbia.edu/kermit/index.html
  9416.  459. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9417.  460. http://www.columbia.edu/kermit/ckermit80.html#top
  9418.  461. http://www.columbia.edu/kermit/ckermit80.html#contents
  9419.  462. http://www.columbia.edu/kermit/ckermit.html
  9420.  463. http://www.columbia.edu/kermit/index.html
  9421.  464. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9422.  465. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9423.  466. http://www.columbia.edu/kermit/ckermit80.html#x9.6
  9424.  467. http://www.columbia.edu/kermit/ckermit80.html#top
  9425.  468. http://www.columbia.edu/kermit/ckermit80.html#contents
  9426.  469. http://www.columbia.edu/kermit/ckermit.html
  9427.  470. http://www.columbia.edu/kermit/index.html
  9428.  471. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9429.  472. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9430.  473. http://www.columbia.edu/kermit/ckermit80.html#top
  9431.  474. http://www.columbia.edu/kermit/ckermit80.html#contents
  9432.  475. http://www.columbia.edu/kermit/ckermit.html
  9433.  476. http://www.columbia.edu/kermit/index.html
  9434.  477. http://www.columbia.edu/kermit/ckermit80.html#top
  9435.  478. http://www.columbia.edu/kermit/ckermit80.html#contents
  9436.  479. http://www.columbia.edu/kermit/ckermit.html
  9437.  480. http://www.columbia.edu/kermit/index.html
  9438.  481. http://www.columbia.edu/kermit/ckermit80.html#top
  9439.  482. http://www.columbia.edu/kermit/ckermit80.html#contents
  9440.  483. http://www.columbia.edu/kermit/ckermit.html
  9441.  484. http://www.columbia.edu/kermit/index.html
  9442.  485. http://www.columbia.edu/kermit/ckermit80.html#x9.9.2
  9443.  486. http://www.columbia.edu/kermit/ckermit80.html#top
  9444.  487. http://www.columbia.edu/kermit/ckermit80.html#contents
  9445.  488. http://www.columbia.edu/kermit/ckermit.html
  9446.  489. http://www.columbia.edu/kermit/index.html
  9447.  490. http://www.columbia.edu/kermit/ckermit80.html#top
  9448.  491. http://www.columbia.edu/kermit/ckermit80.html#contents
  9449.  492. http://www.columbia.edu/kermit/ckermit.html
  9450.  493. http://www.columbia.edu/kermit/index.html
  9451.  494. http://www.columbia.edu/kermit/ckermit80.html#top
  9452.  495. http://www.columbia.edu/kermit/ckermit80.html#contents
  9453.  496. http://www.columbia.edu/kermit/ckermit.html
  9454.  497. http://www.columbia.edu/kermit/index.html
  9455.  498. http://www.columbia.edu/kermit/ckermit80.html#x9.2
  9456.  499. http://www.columbia.edu/kermit/ckermit80.html#top
  9457.  500. http://www.columbia.edu/kermit/ckermit80.html#contents
  9458.  501. http://www.columbia.edu/kermit/ckermit.html
  9459.  502. http://www.columbia.edu/kermit/index.html
  9460.  503. http://www.columbia.edu/kermit/ckermit80.html#x4
  9461.  504. http://www.columbia.edu/kermit/ckermit80.html#x4
  9462.  505. http://www.columbia.edu/kermit/ckermit80.html#top
  9463.  506. http://www.columbia.edu/kermit/ckermit80.html#contents
  9464.  507. http://www.columbia.edu/kermit/ckermit.html
  9465.  508. http://www.columbia.edu/kermit/index.html
  9466.  509. http://www.columbia.edu/kermit/ckermit80.html#top
  9467.  510. http://www.columbia.edu/kermit/ckermit80.html#contents
  9468.  511. http://www.columbia.edu/kermit/ckermit.html
  9469.  512. http://www.columbia.edu/kermit/index.html
  9470.  513. http://www.columbia.edu/kermit/ckermit80.html#top
  9471.  514. http://www.columbia.edu/kermit/ckermit80.html#contents
  9472.  515. http://www.columbia.edu/kermit/ckermit.html
  9473.  516. http://www.columbia.edu/kermit/index.html
  9474.  517. http://www.columbia.edu/kermit/ckermit80.html#x4
  9475.  518. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9476.  519. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9477.  520. http://www.columbia.edu/kermit/ckermit80.html#top
  9478.  521. http://www.columbia.edu/kermit/ckermit80.html#contents
  9479.  522. http://www.columbia.edu/kermit/ckermit.html
  9480.  523. http://www.columbia.edu/kermit/index.html
  9481.  524. ftp://ftp.isi.edu/in-notes/rfc2217.txt
  9482.  525. http://www.columbia.edu/kermit/ckermit80.html#top
  9483.  526. http://www.columbia.edu/kermit/ckermit80.html#contents
  9484.  527. ftp://kermit.columbia.edu/kermit/sredird/
  9485.  528. http://www.columbia.edu/kermit/ckermit.html
  9486.  529. http://www.columbia.edu/kermit/index.html
  9487.  530. http://www.columbia.edu/kermit/ckermit70.html#x4.22
  9488.  531. http://www.columbia.edu/kermit/ckermit80.html#top
  9489.  532. http://www.columbia.edu/kermit/ckermit80.html#contents
  9490.  533. http://www.columbia.edu/kermit/ckermit.html
  9491.  534. http://www.columbia.edu/kermit/index.html
  9492.  535. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9493.  536. http://www.columbia.edu/kermit/cuiksd.html
  9494.  537. http://www.columbia.edu/kermit/ckermit80.html#top
  9495.  538. http://www.columbia.edu/kermit/ckermit80.html#contents
  9496.  539. http://www.columbia.edu/kermit/ckermit.html
  9497.  540. http://www.columbia.edu/kermit/index.html
  9498.  541. http://www.columbia.edu/kermit/ckermit80.html#top
  9499.  542. http://www.columbia.edu/kermit/ckermit80.html#contents
  9500.  543. http://www.columbia.edu/kermit/ckermit.html
  9501.  544. http://www.columbia.edu/kermit/index.html
  9502.  545. http://www.columbia.edu/kermit/index.html
  9503.