File: ckermit80.txt

package info (click to toggle)
ckermit 211-15
links: PTS
area: non-free
in suites: squeeze
size: 15,720 kB
ctags: 19,714
sloc: ansic: 315,174; makefile: 9,096; sh: 66
file content (10349 lines) | stat: -rw-r--r-- 468,227 bytes

                           C-Kermit 8.0 Update Notes

   [ [1]Contents ] [ [2]C-Kermit ] [ [3]Kermit Home ]

              Second Supplement to Using C-Kermit, Second Edition

For C-Kermit 8.0

   As of C-Kermit version: 8.0.211
   Date of C-Kermit release: 10 April 2003
   This file last updated: Sat Apr 10 16:36:11 2004

     * IF YOU ARE READING A PLAIN-TEXT version of this document, note
       that it is a plain-text dump of a Web page. You can visit the
       original (and possibly more up-to-date) Web page here:
  [4]http://www.columbia.edu/kermit/ckermit80.html
     * If you are reading the HTML version of this file with a GUI Web
       browser, the features added since C-Kermit 8.0.201 are shown in
       red if your browser and monitor permit. Features that were new to
       versions 8.0.200 and 201 are in black.

Authors: Frank da Cruz and Christine M. Gianone
Address: The Kermit Project
         Columbia University
         612 West 115th Street
         New York NY 10025-7799
         USA
Fax:     +1 (212) 662-6442
E-Mail:  [5]kermit-support@columbia.edu
Web:     [6]http://www.columbia.edu/kermit/
Or:      [7]http://www.kermit-project.org/
Or:      [8]http://www.columbia.nyc.ny.us/kermit/
     _________________________________________________________________

  NOTICES

   This document:
          Copyright  1997, 2002, Frank da Cruz and Christine M. Gianone.
          All rights reserved.

   Kermit 95:
          Copyright  1995, 2002, Trustees of Columbia University in the
          City of New York. All rights reserved.

   C-Kermit:
          Copyright  1985, 2002,
          Trustees of Columbia University in the City of New York. All
          rights reserved. See the C-Kermit [9]COPYING.TXT file or the
          copyright text in the [10]ckcmai.c module for disclaimer and
          permissions.

   When Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or
          SSL/TLS protocol are included:
          Portions Copyright  1990, Massachusetts Institute of
          Technology.
          Portions Copyright  1991, 1993 Regents of the University of
          California.
          Portions Copyright  1991, 1992, 1993, 1994, 1995 by AT&T.
          Portions Copyright  1997, Stanford University.
          Portions Copyright  1995-1997, Eric Young
          <eay@cryptosoft.com>.

   For the full text of the third-party copyright notices, see
   [11]Appendix V.
     _________________________________________________________________

  WHAT IS IN THIS FILE

   This file lists changes made to C-Kermit since version 7.0 was
   released in January 2000. Use this file as a supplement to:

     * The second edition of [12]Using C-Kermit; and:
     * The [13]C-Kermit 7.0 Update Notes. Also available in plain-text
       form as [14]ckermit70.txt.

   until the third edition of Using C-Kermit is published. We apologize
   for the scattered documentation and will consolidate it when we are
   able.
     _________________________________________________________________

   ADDITIONAL FILES Several other files accompany this new Kermit
   release:

   [15]ckututor.html
          C-Kermit Tutorial (for Unix). Also distributed in Nroff form as
          [16]ckuker.nr, the Unix C-Kermit manual page.

   [17]security.htm
          Discussion of Kermit's new authentication and encryption
          features, updated for C-Kermit 8.0.

   [18]telnet.htm
          Detailed documentation of Kermit's Telnet client, updated for
          C-Kermit 8.0.

   [19]ftpscripts.html
          Tutorial: Writing FTP automation scripts

   [20]ckcbwr.html
          Platform-independent C-Kermit hints and tips. Also distributed
          in plain text form as [21]ckcbwr.txt

   [22]ckubwr.html
          Unix-specific C-Kermit hints and tips. Also distributed in
          plain text form as [23]ckubwr.txt.

   [24]ckvbwr.html
          VMS-specific C-Kermit hints and tips. Also distributed in plain
          text form as [25]ckvbwr.txt.

   [26]ckuins.html
          Unix C-Kermit installation instructions. Also distributed in
          plain text form as [27]ckuins.txt.

   [28]ckvins.html
          VMS C-Kermit installation instructions. Also distributed in
          plain text form as [29]ckvins.txt.

   [30]ckccfg.html
          Compile-time configuration options. Also distributed in plain
          text form as [31]ckccfg.txt.

   [32]ckcplm.html
          C-Kermit Program Logic Manual. Also distributed in plain text
          form as [33]ckcplm.txt.

   [34]iksd.html
          Internet Kermit Service Aministrators Guide for Unix.

   [35]skermit.html
          C-Kermit as an SSH Subsystem (SFTP server replacement).

   [ [36]Top ] [ [37]C-Kermit ] [ [38]Kermit Home ]
  __________________________________________________________________________

CONTENTS

     [39]0. WHAT'S NEW
     [40]1. FIXES SINCE VERSION 7.0.196
     [41]2. SSH AND HTTP 
         [42]2.1. SSH Connections
         [43]2.2. HTTP Connections
            [44]2.2.1. HTTP Command Switches
            [45]2.2.2. HTTP Action Commands
            [46]2.2.3. HTTP Headers
            [47]2.2.4. Secure HTTP Connections
            [48]2.2.5. HTTP Variables
            [49]2.2.6. The HTTP Command-Line Personality
     [50]3. THE BUILT-IN FTP CLIENT
         [51]3.1. Making and Managing FTP Connections
            [52]3.1.1. Kermit Command-Line Options for FTP
            [53]3.1.2. The FTP Command-Line Personality
            [54]3.1.3. The FTP URL Interpreter
            [55]3.1.4. Interactive FTP Session Establishment
         [56]3.2. Making Secure FTP Connections
         [57]3.3. Setting FTP Preferences
         [58]3.4. Managing Directories and Files
         [59]3.5. Uploading Files With FTP
            [60]3.5.1. FTP PUT Switches
            [61]3.5.2. Update Mode
            [62]3.5.3. Recovery
         [63]3.6. Downloading Files With FTP
            [64]3.6.1. FTP GET Switches
            [65]3.6.2. Filename Collisions
            [66]3.6.3. Recovery
         [67]3.7. Translating Character Sets
            [68]3.7.1. Character Sets and Uploading
            [69]3.7.2. Character Sets and Downloading
         [70]3.8. FTP Command Shortcuts
         [71]3.9. Dual Sessions
         [72]3.10. Automating FTP Sessions
            [73]3.10.1. FTP-Specific Variables and Functions
            [74]3.10.2. Examples
            [75]3.10.3. Automating Secure FTP Connections
         [76]3.11. Advanced FTP Protocol Features  [77]4. FILE SCANNING
    [78]5. FILE AND DIRECTORY NAMES CONTAINING SPACES
    [79]6. OTHER COMMAND PARSING IMPROVEMENTS
         [80]6.1. Grouping Macro Arguments
         [81]6.2. Directory and File Name Completion
         [82]6.3. Passing Arguments to Command Files
         [83]6.4. More-Prompting
         [84]6.5. Commas in Macro Definitions
         [85]6.6. Arrow Keys
    [86]7. NEW COMMANDS AND SWITCHES
    [87]8. SCRIPTING IMPROVEMENTS
         [88]8.1. Performance and Debugging
         [89]8.2. Using Macros as Numeric Variables
         [90]8.3. New IF Conditions
         [91]8.4. The ON_UNKNOWN_COMMAND and ON_CD Macros
         [92]8.5. The SHOW MACRO Command
         [93]8.6. Arrays
         [94]8.7. New or Improved Built-in Variables and Functions
         [95]8.8. The RETURN and END Commands
         [96]8.9. UNDEFINing Groups of Variables
         [97]8.10. The INPUT and MINPUT Commands
         [98]8.11. Learned Scripts
         [99]8.12. Pattern Matching
         [100]8.13. Dates and Times
         [101]8.14. Trapping Keyboard Interruption
    [102]9. S-EXPRESSIONS
         [103]9.1. What is an S-Expression?
         [104]9.2. Integer and Floating-Point-Arithmetic
         [105]9.3. How to Use S-Expressions
         [106]9.4. Summary of Built-in Constants and Operators
         [107]9.5. Variables
         [108]9.6. Assignments and Scope
         [109]9.7. Conditional Expressions
         [110]9.8. Extensibility
         [111]9.9. Examples
         [112]9.10. Differences from Algebraic Notation
         [113]9.11.Differences from Lisp
    [114]10. FILE TRANSFER
    [115]11. MODEMS AND DIALING
    [116]12. TERMINAL CONNECTION
    [117]13. CHARACTER SETS
    [118]14. DIALOUT FROM TELNET TERMINAL SERVERS
    [119]15. COPING WITH BROKEN KERMIT PARTNERS
    [120]16. NEW COMMAND-LINE OPTIONS
    [121]17. LOGS

   [ [122]Top ] [ [123]C-Kermit ] [ [124]Kermit Home ]
  __________________________________________________________________________

0. WHAT'S NEW

   The Initialization and Customization Files
          C-Kermit 8.0 now supports specification of the initialization
          file name (path) in an environment variable, CKERMIT_INI. It
          also relies far less than before on the initialization for
          functioning. See [125]Section 5 of the Unix C-Kermit
          [126]installation instructions for details. As of version
          8.0.201, C-Kermit also executes your customization file (if you
          have one) even if the initialization file was not found.
          Previously, the customization file was executed by a TAKE
          command in the initialization file (and it still is, if an
          initialization is found).

   Incompatible Changes
          As always, we do our best to avoid changes that break existing
          scripts. However, C-Kermit 8.0 does include a rather pervasive
          syntax change that might alter the behavior of scripts that
          depend on the previous behavior. As described in [127]Section
          5, C-Kermit now accepts doublequotes in most contexts where you
          previously had to use braces to group multiple words into a
          single field, or to force inclusion of leading or trailing
          blanks. Most noticeably, in C-Kermit 7.0 and earlier:

  echo {this is a string}

          would print:

  this is a string

          whereas:

  echo "this is a string"

          printed:

  "this is a string"

          In C-Kermit 8.0, both print:

  this is a string

          To force the doublequotes to be treated as part of the string,
          use either of the following forms:

  echo {"this is a string"}
  echo ""this is a string""

          Similarly, to force braces to be treated as part of the string:

  echo "{this is a string}"
  echo {{this is a string}}

          Other incompatibilities:

         1. Using the SET HOST command to make HTTP connections is no
            longer supported. Instead, use the new HTTP OPEN command,
            described in [128]Section 2.2.

   C-Kermit 7.1 Alpha.01 (8 December 2000)

     Its major new features are those listed in the [129]Table of
          Contents: the FTP client, file scanning, command parsing and
          scripting improvements, S-Expressions, and support for the
          Telnet Com Port Option, plus wider availability of the
          Kerberos, SSL/TLS, and SRP security options for secure Internet
          connections.

   C-Kermit 7.1.199 Alpha.02 (4 January 2001)

          + C-Kermit now accepts [130]FTP, TELNET, and IKSD URLs as its
            first command-line argument.
          + Character-set translation added to the FTP client for
            [131]filenames. 
          + Optional [132]setting of date of incoming files by FTP [M]GET
            from the server date.
          + [133]FTP CHECK filename added to let FTP client check the
            existence of a file on the server.
          + [134]FTP GET /NAMELIST:filename added to get list of server
            filenames into a local file.
          + [135]FTP [M]PUT /SERVER-RENAME:template added to make server
            rename a file as indicated by the template after it has
            arrived completely.
          + FTP [M]GET /SERVER-RENAME:template added to make server
            rename a file as indicated by the template after it has been
            sent completely.
          + FTP [136]VDIRECTORY added for getting verbose directory
            listings from TOPS-20.
          + [137]FTP TYPE TENEX added for transferring 8-bit binary files
            with PDP-10s.
          + Added [138]automatic text/binary mode switching for FTP
            [M]GET, based on filename patterns (e.g. *.zip, *.gz, *.exe
            are binary; *.txt, *.c are text).
          + [139]SET SEND I-PACKETS OFF added for coping with Kermit
            servers that do not support I packets.
          + A new option was added to [140]\fword() and \fsplit() for
            parsing comma-separated lists that might contain empty
            elements.
          + Bug fixes including:
               o {} or "" could not be used as expected to represent the
                 empty string.
               o ,- on a line by itself in a macro definition caused
                 subsequent statements to be skipped.
               o FTP [M]GET didn't work right if path segments were
                 included in the filespec.
               o FTP MGET, if interrupted, did not clear its file list.
               o Various problems with FTP PUT /AS-NAME that nobody
                 noticed.
               o Some FTP messages and displays interfered with each
                 other.
               o Parsing of YESTERDAY, TODAY, and TOMORROW in date-time
                 fields was broken.
               o Automatic old-to-new dialing directory format conversion
                 was broken on VMS.
               o Various source-code portability problems fixed.
          + Improvement of various HELP and SHOW messages.

   C-Kermit 7.1.199 Alpha.04 (1 April 2001)

          + Big changes:
               o Changed default modem type from NONE to GENERIC.
               o Generic dialing now sends no init string at all.
               o Changed default terminal bytesize from 7 to 8.
          + New features:
               o SET SESSION-LOG TIMESTAMPED-TEXT for timestamped session
                 log.
          + New modem types:
               o Conexant modem family
               o Lucent VENUS chipset
               o PCTel V.90 chipset
               o Zoom V.90
               o Zoom V.92
          + FTP client:
               o FTP OPEN /PASSIVE and /ACTIVE switches added.
               o Now works with servers that that don't include path in
                 NLST response.
               o Fixed SEND /RECURSIVE not to follow symlinks (UNIX).
               o SET FTP VERBOSE-MODE default is now OFF instead of ON.
          + Kermit protocol:
               o Fixed what I hope is the last "Receive window full"
                 error.
               o SET PREFIXING or SET CONTROL PREFIX now automatically
                 sets CLEARCHANNEL OFF.
               o Fixed incorrect report of number of files transferred at
                 end of transfer.
               o Fixed SEND /RECURSIVE not to follow symlinks (UNIX).
          + UNIX:
               o HTTP and shadow passwords enabled for SCO 5.0.6.
               o Even with SET FILENAMES CONVERTED, spaces were still
                 accepted in incoming filenames; now they are converted
                 to underscores.
               o Added support for compile-time mktemp()/mkstemp()
                 selection.
          + VMS:
               o Session-log format for scripted sessions fixed.
          + Scripting:
               o Fixed \frdir() not to follow symlinks (UNIX).
               o Fixed \fday() not to dump core for dates prior to 17 Mar
                 1858.
          + General:
               o "Closing blah..." message upon exit could not be
                 surpressed.
               o Added /PAGE and /NOPAGE to DELETE switches.
               o Added GO response for DELETE /ASK (delete all the rest
                 without asking).
               o Added GO response to "more?" prompt (for multi-page
                 screen output).
               o Updated HELP texts.

   C-Kermit 7.1.199 Beta.01 (10 May 2001)

          + FTP client verbosity adjustments.
          + Bug with generic modem dialing pausing several secs fixed.
          + SET HOST /USER:, SET LOGIN USERID, etc, fixed when given no
            user ID.
          + A couple \v(dm_blah) dial modifier variables added.
          + "--version" command-line switch added.
          + Fixed NetBSD serial-port DTR handling.
          + Lots of syntax cleanups for Flexelint and gcc -Wall.
          + Fixed modem-type aliases to not take precedence over real
            names.
          + Fixed funny treatment of doublequotes by ECHO command.
          + Enabled SET SESSION-LOG for VMS and other non-UNIX platorms.
          + Fixed changing direction in command history buffer.
          + Fixed handling of IKSD URLs.
          + Made sure DELETE prints a message if it got any errors.

   C-Kermit 8.0.200 Beta.02 (28 June 2001)

          + Major version number increased from 7 to 8.
          + [141]SSH command.
          + More-consistent Kermit protocol defaults.
          + CONNECT idle timeout and action selection.
          + CONNECT status variable.
          + A way to allocate more space for filename lists.
          + Pseudoterminal handler fixed for late-model Linuxes.
          + Command-line option -dd for timestamped debug log.
          + Download directory now works for external protocols too.
          + GREP /COUNT:variable.
          + SET ATTRIBUTE RECORD-FORMAT { OFF, ON }.
          + Bug fixes.

   C-Kermit 8.0.200 Beta.03 (9 Sep 2001)

          + [142]HTTP 1.1 connections and scripting
          + [143]ON_CTRLC macro for trapping Ctrl-C in scripts
          + [144]Date-time parsing improvements, timezones, comparison,
            arithmetic
          + [145]Pattern-matching improvements
          + FTP improvements
          + SET EXIT HANGUP { ON, OFF }
          + SET FILE EOF { CTRL-Z, LENGTH }
          + ASK[Q] /TIMEOUT
          + Bug fixes
          + New platforms

   C-Kermit 8.0.200 Beta.04 (16 Nov 2001)

          + [146]New Unix man page
          + [147]New Unix installation instructions
          + SET TELOPT policies are now enforced on non-Telnet ports if
            the server begins Telnet negotiations.
          + SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT }.
          + UUCP lockfile creation race condition fixed.
          + Dialout, modem signals, hangup, hardware flow control, etc,
            tested extensively on many platforms, numerous problems
            fixed.
          + Improved hints when dialing fails.
          + SET STOP-BITS 2 can now be given without SET FLOW HARDWARE.
          + Major improvements in RFC 2217 Telnet Com-Port Control.
          + Improved ability to REDIAL a modem server port.
          + kermit -h now shows the command name in the usage usage
            string.
          + kermit -h now shows ALL command-line options.
          + kermit -s blah, where blah is a symlink, now works.
          + --noperms command-line option = SET ATTRIBUTE PERMISSIONS
            OFF.
          + HTTP and HTTPS URLs now supported on the command line.
          + An http command-line personality is now available.
          + Initialization file streamlined to load faster, anachronisms
            removed.
          + Updated NEWS, INTRO, HELP text, SHOW commands. In particular,
            see SHOW COMM, HELP SET LINE, HELP WAIT.
          + Date/time arithmetic routines converted from floating-point
            to integer arithmetic (internally) for greater accuracy and
            portability.
          + Quoted strings containing commas no longer break macro
            execution.
          + Dynamic Kermit file-transfer timeouts are now much more
            aggressive.
          + New "hot keys" to turn debug.log on/off during file transfer.
          + Improved hints when file transfer fails.
          + FTP CD orientation messages are now printed.
          + -R now accepted on the FTP command line to request Recursion.
          + -m allows Active or Passive mode to be chosen on the FTP
            command line.
          + -dd on the FTP command line creates a timestamped debug.log.
          + FTP command-line security options filled in.
          + Improved automatic text/binary mode switching for MGET.
          + Removed spurious error messages that sometimes occur during
            MGET.
          + DIRECTORY, GREP, TYPE, HEAD, and TAIL now have a /OUTPUT:file
            option.
          + TYPE /NUMBER adds line numbers.
          + CAT = TYPE /NOPAGE; MORE = TYPE /PAGE.
          + GETOK ?-help fixed.
          + \v(timestamp) (= "\v(ndate) \v(time)")
          + \v(hour) (hour of the day, 0-23)
          + \funix2dospath() converts a UNIX path (/) to a DOS one (\).
          + \fdos2unixpath() converts a DOS (Windows, OS/2) path to a
            UNIX one.
          + \fkeywordval() parses name=value pair, allows macro keyword
            parameters.
          + We now make every attempt to not write passwords to the
            debug.log.
          + New Certficate Authority certificates file, includes the
            Kermit Project at Columbia University so you can access our
            IKSD securely.
          + Secure targets improved and better documented in Unix
            makefile.
          + All Linux (libc and glibc) builds consolidated under "make
            linux".
          + HP-UX makefile targets now have consistent names.
          + New aix50 and aix51 targets added.

   C-Kermit 8.0.200 Final (12 Dec 2001)

          + Remote/local-mode confusion on some platforms introduced in
            Beta.04, fixed.
          + Many of the makefile targets adjusted, new ones added.
          + New "make install" target should please most people.
          + New command: SHOW IKSD.
          + FTP over TLS.
          + Last-minute touchups to text messages, HELP text, etc.
          + Enable modem-signal reading for SCO OSR5 and Unixware 7.
          + Special superfast TRANSMIT /BINARY /NOECHO /NOWAIT mode
            added.
          + Fixed PBX dialing in unmarked-area-code case.
          + Improved SHOW COMMUNICATIONS tells lockfile directory,
            typical dialout device name.
          + Some FTP OPEN command parsing problems fixed.
          + Some errors in date arithmetic fixed.
          + New command: SET TERMINAL AUTODOWNLOAD { ..., ERROR { STOP,
            CONTINUE } }
          + New command: HELP FIREWALL.
          + SET MODEM HANGUP-METHOD DTR added as synomym for RS232-SIGNAL
          + Support for secure URL protocols added: telnets:, ftps:,
            https:.

   C-Kermit 8.0.201 (8 Feb 2002)

          + Installability as an [148]SSH v2 Subsystem.
          + [149]SET LOCUS command.
          + [150]L-versions of CD, DIR, DELETE, MKDIR, etc, to force
            local execution.
          + [151]USER and ACCOUNT added as synonyms for FTP USER and FTP
            ACCOUNT.
          + [152]SHOW VARIABLES now accepts a list of variables.
          + Rudimentary support for [153]Caller ID when receiving phone
            calls.
          + Up/Down [154]Arrow-key navigation of command history buffer.
          + [155]Automatic execution of customization file if init file
            is missing.

   C-Kermit 8.0.206 Beta.01 (11 Oct 2002)

        New commands:

               o ORIENTATION lists location-related variables and their
                 values.
               o KCD changes to special directories by their symbolic
                 names ("kcd ?" for a list).
               o SET CD HOME path to specify home directory for CD and
                 KCD commands.
               o CONTINUE given at top level is equivalent to END --
                 handy when PROMPT'ed out of a script, to continue the
                 script.

        New switches or operands for existing commands:

               o GETOK /TIMEOUT
               o ASK, ASKQ, GETOK /QUIET (suppresses error message on
                 timeout)
               o COPY /APPEND now allows concatenating multiple source
                 files into one dest file.
               o SET TCP { HTTP-PROXY, SOCKS-SERVER } /USER, /PASSWORD.
               o DIRECTORY command now accepts multiple filespecs, e.g.
                 "dir a b c".

        SET QUIET ON now also applies to:

               o SET HOST connection progress messages.
               o "Press the X or E key to cancel" file-transfer message.
               o REMOTE CD response.
               o REMOTE LOGIN response.

        Improvements and new features:

               o Numerous FTP client fixes and new features, listed
                 below.
               o C-Kermit, when in remote mode at the end of a file
                 transfer, now prints a one-line "where" message. Control
                 with SET TRANSFER REPORT.
               o Unix makefile "install" target now creates an UNINSTALL
                 script.
               o Improved operation and performance on RFC 2217 Telnet
                 connections.
               o Improved CONNECT (interactive terminal connection)
                 performance.
               o HELP text updated for many commands.

        New or fixed makefile targets:

               o Solaris 9 (several variations)
               o Concurrent PowerMAX
               o Mac OS X 10.2
               o FreeBSD 1.0
               o FreeBSD 4.6, 5.0
               o AIX 5.2, 5.3

        Bugs fixed (general):

               o Failure to run in VMS Batch fixed.
               o LDIRECTORY fixed to run Kermit's built-in DIRECTORY
                 command rather than an external one.
               o Fixed Solaris and other SVORPOSIX builds to find out
                 their full hostnames rather than just the "uname -n"
                 name.
               o Fixed some problems matching strings that start with
                 ".".
               o Fixed some problems matching pattern that contain
                 {a,b,c} lists.
               o Fixed erroneous reporting of text-mode reception as
                 binary when sender did not report the file size
                 (cosmetic only).
               o Many problems with SWITCH statements fixed.
               o Fixed SET OPTIONS DIRECTORY /DOTFILES to work for server
                 too.
               o Fixed DELETE to print an error message if the file was
                 not found.
               o Fixed SET CONTROL UNPREFIX ALL and SET PREFIXING NONE to
                 do the same thing.
               o Fixed bugs executing macros from within the ON_EXIT
                 macro.
               o \fday() and \fnday() fixed for dates prior to 17 Nov
                 1858.
               o Serial speed-changing bug in Linux fixed.
               o "Unbalanced braces" script parsing errors when using
                 \{number} fixed.
               o "if defined \v(name)" fixed to behave as described in
                 the book.
               o Fixed Problems caused by LOCAL variables whose names are
                 left substrings of macro names.
               o The INPUT command was fixed to honor the PARITY setting.
               o Fixed bug with COPY to existing file that is longer than
                 source file.
               o REINPUT command failed to strip braces/quotes around its
                 target string.
               o Network directory lookups didn't work for SSH
                 connections.
               o REMOTE SET { FILE, TRANSFER } CHARACTER-SET fixed.
               o Closed some holes whereby an incompletely received file
                 was not deleted when SET FILE INCOMPLETE is DISCARD,
                 e.g. when the Kermit is hung up upon.
               o SET XFER CHARACTER-SET TRANSPARENT fixed to do the same
                 as SET XFER TRANSLATION OFF.
               o SET HOST PTY (e.g. SSH) connection fixed to pass along
                 window-size changes.
               o C-Kermit search path for TAKE files was accidentally
                 disabled.

        FTP client bugs fixed:

               o Character set translation was broken on little-endian
                 (e.g. PC) architectures.
               o FTP PUT /SERVER-RENAME:, /RENAME-TO:, /MOVE-TO: switches
                 were sticky.
               o Make SET TRANSFER MODE MANUAL apply to FTP.
               o Make SET FILE INCOMPLETE { KEEP, DISCARD } apply to FTP.
               o FTP MGET /UPDATE handled equal times incorrectly.
               o FTP MGET /RECOVER fixed to ignore file dates, use only
                 size.
               o FTP MGET /RECOVER sometimes downloaded files it didn't
                 need to.
               o FTP downloads with TRANSFER DISPLAY BRIEF could give
                 misleading error messages.
               o FTP MGET temp file not deleted if FTP DEBUG set to OFF
                 after it was ON.
               o LOCUS not switched back when FTP connection is lost.
               o Set incoming file date even if it was not completely
                 received.
               o FTP MGET sent SIZE and MDTM commands even when it didn't
                 have to.
               o FTP MGET sent SIZE and MDTM commands even when it knew
                 they wouldn't work.
               o FTP MGET failed if no files were selected for download.
               o FTP MGET a* b* c* would fail to get any c*'s if no b*'s
                 existed.
               o Big problems canceling MGET with Ctrl-C.
               o Some extraneous LOCUS dialogs squelched.
               o Some inconsistencies in SET FTP FILENAMES AUTO fixed.
               o Fixed file-descriptor pileup after multiple MGETs when
                 using mkstemp().
               o Fixed "mget foo", where foo is a directory name.

        FTP improvements:

               o New [156]FTP protocol features added (FEAT, MLSD).
               o FTP MGET /RECURSIVE now works as expected if server
                 supports MLSD.
               o FTP MGET /DATES-DIFFER to download if local and remote
                 file dates differ.
               o FTP DATES default changed to ON.
               o FTP MPUT, MGET /EXCEPT now allows up to 64 patterns (up
                 from 8).
               o Top-level SITE and PASSIVE commands added for
                 convenience.
               o MGET /COLLISION:APPEND /AS-NAME:newfile *.* puts all
                 remote files into one local file.
               o SET FTP SERVER-TIME-OFFSET for when server has wrong
                 timezone set.
               o Allow for alternative server interpretations of [M]MPUT
                 /UNIQUE.
               o SET FTP ANONOMOUS-PASSWORD lets you specify the default
                 anonymous password.
               o Allow "GET /RECURSIVE path/file" to force local
                 subdirectory creation.
               o SET FTP DISPLAY is like SET TRANSFER DISPLAY but applies
                 only to FTP.
               o FTP { ENABLE, DISABLE } new-protocol-feature-name.
               o FTP MGET /NODOTFILES.
               o Debug log now records FTP commands and responses in
                 grep-able format.

   [ [157]Top ] [ [158]Contents ] [ [159]C-Kermit ] [ [160]Kermit Home ]
  __________________________________________________________________________

1. FIXES SINCE VERSION 7.0.196 First, the changes from 7.0.196 to 7.0.197...
Source and makefile tweaks to get successful builds on platforms that were not
available in time for the 7.0 release:

     * 4.2BSD
     * 4.3BSD
     * AIX 4.3
     * AT&T 3B2 and 3B20
     * BeOS 4.5
     * CLIX
     * Interactive UNIX System V/386 R3.2 V4.1.1
     * OS-9/68000
     * OSF/1 1.3.
     * PS/2 AIX 1.2.1
     * SCO OSR5.0.x
     * SCO Xenix 2.3.4
     * SINIX 5.41/Intel
     * Stratus FTX
     * Stratus VOS
     * SunOS 4.1 with X.25
     * Ultrix 4.2
     * Unixware 2.0

   There were no functional changes from 196 to 197.

   Fixes applied after C-Kermit 7.0.197 was released:

   Source code: Big flexelint and "gcc -Wall" audit and cleanup.

   Configuration:
     * Solaris RTS/CTS (hardware flow control) didn't work.
     * BSDI RTS/CTS worked only in one direction.
     * FreeBSD 4.0 with ncurses 5.0 broke interactive command parsing.
     * QNX-32 build lacked -DBIGBUFOK so couldn't execute big macros.

   Connections:
     * SET HOST /PTY didn't work on some platforms.
     * Broken SET HOST /USER:xxx /PASSWORD:yyy /ACCOUNT:zzz switches
       fixed.
     * Transparent printing was broken in Unix.
     * ANSWER 0 (wait forever) didn't work.
     * Some problems in Multitech modem command strings.
     * Spurious "?Sorry, can't condition console terminal" errors.
     * Disabling modem command strings by setting them to nothing broke
       dialing.
     * SET DIAL TIMEOUT value was usually ignored.
     * SET DIAL METHOD PULSE didn't work.
     * Certain modem commands, if changed, not refreshed if modem type
       changed.
     * SET SESSION-LOG command was missing from VMS.
     * VMS session log format fixed for scripts.
     * HANGUP by dropping DTR didn't work in NetBSD.
     * SET FLOW /AUTO versus SET FLOW confusion fixed.
     * Spurious secondary Solaris lockfile removed.
     * SCO OSR5 DTR On/Off hangup.
     * UUCP lockfile race condition.

   Commands and scripts:
     * Missing CAUTIOUS and FAST commands restored.
     * Broken PTY command in late-model Linuxes fixed (API changed).
     * Fixed off-by-one error in command recall when switching direction.
     * Fixed recall of commands that contain '?'.
     * COPY /SWAP-BYTES didn't work on some architectures.
     * Various combinations of COPY switches didn't work.
     * Various problems with COPY or RENAME with a directory name as
       target.
     * SHIFT didn't decrement \v(argc) if used within IF, ELSE, or SWITCH
       block.
     * SHIFT didn't affect the \%* variable.
     * Divide by zero improperly handled in some \function()s.
     * Problems with RETURN from right-recursive functions.
     * FSEEK /LINE \%c LAST didn't work if already at end.
     * Some buffer vulnerabilities and potential memory leaks were
       discovered and fixed.
     * \frdirectory() fixed not to follow symbolic links.
     * SET EXIT WARNING OFF fixed to work when EXIT given in a script.
     * Missing DELETE and MKDIR error message fixed.
     * \fday() core dump for ancient dates fixed.

   File transfer:
     * SEND /COMMAND was broken.
     * CRECEIVE was broken (but RECEIVE /COMMAND was OK).
     * Quoting wildcard chars in filenames didn't work.
     * Problems canceling streaming file transfers with X or Z.
     * Problems shifting between streaming and windowing file transfer.
     * Non-FULL file-transfer displays erroneously said STREAMING when
       not.
     * An active SEND-LIST prevented GET from working.
     * SET SERVER GET-PATH interpretation of relative names like "." was
       wrong.
     * The MAIL command was broken.
     * "kermit -s *" might have skipped some files.
     * Transaction log entries were not made for external protocol
       transfers.
     * File count report fixed to show number of files actually
       transferred.
     * Fixed filename conversion to convert spaces to underscores.
     * Made SET PREFIXING / SET CONTROL PREFIX also adjust CLEARCHANNEL.
     * More "Receive window full" errors fixed.
     * Broken terminal buffering after curses display in Solaris fixed.
     * SET FILE INCOMPLETE DISCARD did not work in all cases.
     * Packet log changed to reformat the start-of-packet character
       printably.
     * Dynamic timeouts could grow ridiculously large.

   Character sets:
     * Hebrew-7 translations missed the letter Tav.
     * C1 area of CP1252 was ignored.
     * SET TRANSFER CHARACTER-SET TRANSPARENT could give garbage
       translations.
     * TRANSLATE might not work on Little Endian architectures.
     * Insufficient range checking in certain TRANSLATE operations.

   The following bugs in C-Kermit 8.0.200 were fixed in 8.0.201:

     * An obscure path through the code could cause the Unix version of
       C-Kermit to dump core during its startup sequence. This happened
       to only one person, but now it's fixed.
     * When C-Kermit 8.0 is in Kermit server mode and the client says
       "get blah", where blah (on the server) is a symlink rather than a
       real file, the server unreasonably refused to send the linked-to
       file.
     * When C-Kermit is an FTP client and says "get foo/bar" (i.e. a
       filename that includes one or more path segments), it failed to
       accept the incoming file (this happened only with GET, not MGET).
     * Array references should be case insensitive but only lowercase
       array letters were accepted.
     * SHOW VARIABLES dumped core on \v(sexpression) and \v(svalue).
     * Spurious refusals of remote directory listings if the remote
       server's date was set in the past.
     * In AIX, and maybe elsewhere too, Kermit's COPY command always
       failed with "Source and destination are the same file" when the
       destination file didn't exist.
     * The VMS version of C-Kermit did not work in Batch or when SPAWN'd.
       To compound the problem, it also pretty much ignored the -B and -z
       command-line options, whose purpose is to work around such
       problems.
     * C-Kermit 8.0 could not be built on IRIX 5.x.
     * The C-Kermit 8.0 build for QNX6 said it was an "(unknown
       version)".

   Other fixes are listed in the [161]previous section.

   [ [162]Top ] [ [163]Contents ] [ [164]C-Kermit ] [ [165]Kermit Home ]
  __________________________________________________________________________

2. SSH AND HTTP

  2.1. SSH Connections

     This section does not apply to [166]Kermit 95 2.0, which has its
     own built-in SSH client, which is documented [167]SEPARATELY. 

   On most UNIX platforms, C-Kermit can make SSH (Secure SHell)
   connection by running the external SSH command or program through its
   pseudoterminal interface. The command is:

   SSH text
          Tells Kermit to start the external SSH client, passing the
          given text to it on the command line. Normally the text is just
          the hostname, but it can be anything else that is acceptable to
          the ssh client. If the command succeeds, the connection is made
          and Kermit automatically enters CONNECT (terminal) mode. You
          can use the SSH command to make a connection to any host that
          has an SSH server.

   Kermit's SSH command gives you all the features of Kermit on an SSH
   connection: command language, file transfer, character-set
   translation, scripting, and all the rest. By default, C-Kermit invokes
   SSH with "-e none", which disables the ssh escape character and makes
   the connection transparent for purposes of file transfer. You can,
   however, change the SSH invocation to whatever else you might need (an
   explicit path, additional command-line arguments, etc) with:

   SET SSH COMMAND text
          Specifies the system command that Kermit's SSH command should
          use to invoke the external SSH client. Use this command to
          supply a specific path or alternative name, or to include
          different or more command-line options.

   In most cases, these connections work quite well. They can be scripted
   like any other connection, and file transfer goes as fast as, or
   faster than, on a regular Telnet connection. In some cases, however,
   the underlying pseudoterminal driver is a limiting factor, resulting
   in slow or failed file transfers. Sometimes you can work around such
   problems by reducing the Kermit packet length. Note that Kermit does
   not consider SSH connections to be reliable, so it does not offer to
   use streaming in Kermit protocol transfers (but you can force it with
   SET RELIABLE or SET STREAMING if you wish).

   The SSH command is like the TELNET command: it enters CONNECT mode
   automatically when the connection is made. Therefore, to script an SSH
   connection, use:

  set host /pty ssh -e none [ other-options ] host
  if fail ...

   to make the connection.

   Here's a sequence that can be used to make a connection to a given
   host using Telnet if the host accepts it, otherwise SSH:

  if not defined \%1 exit 1 Usage: \%0 host
  set quiet on
  set host \%1 23 /telnet
  if fail {
      set host /pty ssh -l \m(user) -e none \%1
      if fail exit 1 \%1: Telnet and SSH both fail
      echo SSH connection to \%1 successful
  } else {
      echo Telnet connection to \%1 successful
  }

   In SSH v2, it is possible to make an SSH connection direct to a Kermit
   server system if the host administrator has configured the SSH server
   to allow this; [168]CLICK HERE for details.

   Since Kermit uses external ssh client software, and since there are
   different ssh clients (and different releases of each one), the exact
   command to be used to make an SSH/Kermit connection can vary. Here is
   the command for the OpenSSH 3.0.2p1 client:

set host /pipe ssh -e none [ -l username ] -T -s hostname kermit

   Example:

set host /pipe ssh -e none -l olga -T -s hq.xyzcorp.com kermit

   The SSH client might or might not prompt you for a password or other
   information before it makes the connection; this depends on your SSH
   configuration (your public and private keys, your authorized hosts
   file, etc). Here's a brief synopsis of the OpenSSH client command
   syntax ("man ssh" for details):

   -e none
          This tells the SSH client to use no escape character. Since we
          will be transferring files across the connection, we don't want
          the connection to suddenly block because some character in the
          data.

   -l username
          This is the username on the remote host. You can omit the -l
          option and its argument if your local and remote usernames are
          the same. If they are different, you must supply the remote
          username.

   -T
          This tells the SSH client to tell the SSH server not to
          allocate a pseudoterminal. We are not making a terminal
          connection, we don't need a terminal, and in fact if a terminal
          were allocated on the remote end, the connection would not
          work.

   -s ... kermit
          This tells the SSH client to tell the SSH server to start the
          specified subsystem ("kermit") once the connection is made. The
          subsystem name comes after the hostname.

   hostname
          The IP host name or address of the desired host.

   You might want to include other or additional ssh command-line
   options; "man ssh" explains what they are. Here are some examples for
   the OpenSSH 3.0.2p1 client:

   -oClearAllForwardings yes
   -oForwardAgent no
   -oForwardX11 no
   -oFallbackToRsh no
          These ensure that a secure connection is used and that the
          connection used for file transfer is not also used for
          forwarding other things that might be specified in the
          ssh_config file.

   -oProtocol 2
          (i.e. SSH v2) Ensures that the negotiated protocol supports
          subsystems.

   Once you have an SSH connection to a Kermit server, it's just like any
   other connection to a Kermit server (and very similar to a connection
   to an FTP server). You give the client file transfer and management
   commands for the server, and the server executes them. Of course you
   can also give the client any other commands you wish.

   [ [169]SSH Kermit Server Subsystem ] [ [170]Kermit 95 Built-in SSH
   Client ]
     _________________________________________________________________

  2.2. HTTP Connections

   Hypertext Transfer Protocol, or HTTP, is the application protocol of
   the World Wide Web (WWW), used between Web browsers (clients) and Web
   servers. It allows a client to get files from websites, upload files
   to websites, delete files from websites, get information about website
   directories and files, and interact with server-side CGI scripts.
   C-Kermit includes an HTTP client capable of both clear-text and secure
   HTTP connections, that can do all these tasks and can be automated
   through the Kermit scripting language.

   Although C-Kermit 7.0 could make HTTP connections to Web servers, it
   could do so only when no other connection was open, and the procedure
   was somewhat awkward. C-Kermit 8.0 improves matters by:

     * Allowing an HTTP connection to be open at the same time as a
       regular SET LINE or SET HOST connection, and also at the same time
       as an FTP connection ([171]Section 3);
     * Upgrading the HTTP protocol level from 1.0 to 1.1, thus allowing
       for persistent connections, in which a series of commands can be
       sent on the same connection, rather than only one as in HTTP 1.0
       (and C-Kermit 7.0);
     * Providing for "one-shot" URL-driven HTTP operations such as GET or
       PUT.
     * Providing a distinct HTTP command-line personality.

   Persistent HTTP connections are managed with the following commands:

   HTTP [ switches ] OPEN [ security-options ] host-or-url [ port ] 
          Opens a persistent connection to the specified host (IP host
          name or address) on the specified port. If any switches
          (options, listed in the next section) are included, their
          values are saved and used for all subsequent HTTP action
          commands on the same connection. If no port is specified, HTTP
          (80) is used. A Uniform Resource Locator (URL, [172]RFC 1738)
          can be given instead of a hostname (or address) and port (but
          the URL can not include a directory/file path). The security
          options are explained [173]below. The HTTP OPEN command
          replaces the C-Kermit 7.0 SET HOST hostname HTTP command, which
          no longer works with HTTP GET and related commands.

   HTTP CLOSE
          Closes any open HTTP connection and clears any saved switch
          values.

   A URL starts with a protocol name, which must be http or https in this
   case; optionally includes a username and password; and must contain a
   host name or address:

  protocol://[user[.password]]@host[:port][URI]

   HTTP is Hypertext Transfer Protocol. HTTPS is the secure (SSL/TLS)
   version of HTTP. The TCP service port is derived from the protocol
   prefix (so normally the ":port" field is omitted). Thus the URL
   protocol name specifies a default TCP service port and the URL user
   and password fields can take the place of the /USER and /PASSWORD
   switches ([174]Section 2.2.1). The optional URI is a "compact string
   of characters for identifying an abstract or physical resource"
   ([175]RFC 2396), such as a file. It must begin with a slash (/); if
   the URI is omitted, "/" is supplied. Examples:

   http open http://www.columbia.edu/
          Equivalent to http open www.columbia.edu or http open
          www.columbia.edu http.

   http open https://olga.secret@www1.xyzcorp.com/
          Equivalent to http /user:olga /pass:secret open
          www1.xyzcorp.com https.

   Persistence is accomplished unilaterally by C-Kermit 8.0. An HTTP 1.0
   server closes the connection after each action. Although HTTP 1.1
   allows multiple actions on the same connection, an HTTP 1.1 server
   tends to close the connection if it is idle for more than a few
   seconds, to defend itself against denial-of-service attacks. But when
   you use Kermit's HTTP OPEN command to create a connection, Kermit
   reopens it automatically (if necessary) for each HTTP action until you
   close it with HTTP CLOSE, regardless of the server's HTTP protocol
   version, or how many times it closes the connection.

   Firewalls can be negotiated through proxies with the following
   commands:

   SET TCP HTTP-PROXY [ host[:port] ]
          If a host (by hostname or IP address) is specified, Kermit uses
          it as a proxy server when attempting outgoing TCP connections
          -- not only HTTP connections, but all TCP/IP connections,
          Telnet and FTP included. This allows Kermit to adapt to the
          HTTP firewall penetration method (as opposed to other methods
          such as SOCKS4). If no hostname or ip-address is specified, any
          previously specified Proxy server is removed. If no port number
          is specified, the "http" service is used. This command must be
          given before the HTTP OPEN command if a proxy is to be used or
          canceled.

   HTTP [ switches ] CONNECT host[:port]
          Instructs the HTTP server to act as a proxy, establishing a
          connection to the specified host (IP hostname or address) on
          the given port (80 = HTTP by default) and to redirect all data
          transmitted between Kermit and itself to the given host for the
          life of the connection. This command is to be used only for
          debugging HTTP proxy connections. If a proxy connection is
          required, instruct Kermit to use the proxy with the SET TCP
          HTTP-PROXY command.

    2.2.1. HTTP Command Switches

   HTTP switches, like all other switches, are optional. When HTTP
   switches are included with the HTTP OPEN command, they apply
   automatically to this and all subsequent HTTP actions (GET, PUT, ...)
   on the same connection until an HTTP CLOSE command is given. So if you
   include switches (or the equivalent URL fields, such as user and
   password) in the HTTP OPEN command, you can omit them from subsequent
   commands on the same connection. If the connection has closed since
   your last command, it is automatically reopened with the same options.

   If you include switches with an HTTP action command (such as GET or
   PUT), they apply only to that command.

   /USER:name
          To be used in case a page requires a username for access. The
          username is sent with page requests. If it is given with the
          OPEN command it is saved until needed. If a username is
          included in a URL, it overrides the username given in the
          switch. CAUTION: Username and password (and all other
          information, including credit card numbers and other material
          that you might prefer to protect from public view) are sent
          across the network in clear text on regular HTTP connections,
          but authentication is performed securely on HTTPS connections.

   /PASSWORD:text
          To be used in case a web page requires a password for access.
          The password is sent with page requests. If it is given with
          the OPEN command it is saved until needed. If a password is
          given in a URL, it overrides the one given here. CAUTION: (same
          as for /USER:).

   /AGENT:user-agent
          Identifies the client to the server. Overrides the default
          agent string, which is "C-Kermit" (for C-Kermit) or "Kermit-95"
          (for Kermit 95).

   /ARRAY:array-designator
          Tells Kermit to store the response headers in the given array,
          one line per element. The array need not be declared in
          advance. Example: /array:&a.

   /TOSCREEN
          Tells Kermit to display any response text on the screen. It
          applies independently of the output file specification; thus it
          is possible to have the server response go to the screen, a
          file, both, or neither.

   /HEADER:header-item(s)
          Used for specifying any optional headers to be sent with HTTP
          requests.

  /HEADER:tag:value

          To send more than one header, use braces for grouping:

  /HEADER:{{tag:value}{tag:value}...}

          For a list of valid tags and value formats see [176]RFC 2616,
          "Hypertext Transfer Protocol -- HTTP/1.1". A maximum of eight
          headers may be specified.

    2.2.2. HTTP Action Commands

   HTTP actions can occur within a persistent connection, or they can be
   self-contained ("connectionless"). A persistent HTTP connection begins
   with an HTTP OPEN command, followed by zero or more HTTP action
   commands, and is terminated with an HTTP CLOSE command:

  http open www.columbia.edu
  if failure stop 1 HTTP OPEN failed: \v(http_message)
  http get kermit/index.html
  if failure stop 1 HTTP GET failed: \v(http_message)
  (more actions possible here...)
  http close

   A self-contained HTTP action occurs when a URL is given instead of a
   remote file name to an HTTP action command. In this case, Kermit makes
   the HTTP connection, takes the action, and then closes the connection.
   If an HTTP connection was already open, it is closed silently and
   automatically.

  http get http://www.columbia.edu/kermit/index.html

   Kermit's HTTP action commands are as follows. Switches may be included
   with any of these to override switch (or default) values given in the
   HTTP OPEN command.

   HTTP [ switches ] GET remote-filename [ local-filename ]
          Retrieves the named file from the server specified in the most
          recent HTTP OPEN command for which a corresponding HTTP CLOSE
          command has not been given. The filename may not include
          wildcards (HTTP protocol does not support them). If no HTTP
          OPEN command is in effect, this form of the HTTP GET command
          fails. The default local filename is the same as the remote
          name, but with any pathname stripped. For example, the command
          http get kermit/index.html stores the file in the current local
          directory as index.html. If the /HEADERS: switch is included,
          information about the file is also stored in the specified
          array (explained in [177]Section 2.2.3). All files are
          transferred in binary mode. HTTP does not provide for
          record-format or character-set conversion.

   HTTP [ switches ] GET url [ local-filename ]
          When HTTP GET is given a URL rather than a filename, Kermit
          opens a connection to the designated server (closing any
          previously open HTTP connection), gets the file, and then
          closes the connection. If the URL does not include a filename,
          index.html is supplied. This is the self-contained one-step
          "connectionless" method for getting a file from a Web server.
          The data is not interpreted; HTTP GET is like "lynx -source"
          rather than "lynx -dump".

   In the remaining HTTP action commands, the distinction between a
   remote filename and a URL are the same as in the HTTP GET command.

   HTTP [ switches ] HEAD remote-filename-or-url [ local-filename ]
          Like GET except without actually getting the file; instead it
          retrieves only the headers. If the /ARRAY: or /TOSCREEN switch
          is included, there is no default local output filename but you
          can still specify one. If neither of these switches is
          included, the default local filename is the same as the remote
          filename, but with any path stripped and with ".head" appended.
          The HEAD command can be used in a script with the /ARRAY:
          switch to retrieve information about the requested resource to
          determine whether the resource should actually be retrieved
          with a subsequent GET request.

   HTTP [ switches ] INDEX remote-directory-or-url [ local-filename ]
          Asks the server to send a listing of the files in the given
          server directory. This command is not supported by most Web
          servers. Even when it is supported, there is no standard format
          for the listing.

   HTTP [ switches ] POST [ /MIME-TYPE:type ] source-file
          remote-path-or-url [ result-file ]
          Sends data to a process running on the remote host; the result
          is usually an HTML file but could be anything. The data to be
          posted must be read from a local file (the source-file). If a
          result file is specified, Kermit stores the server's response
          in it.

   HTTP [ switches ] PUT [ MIME-TYPE:type ] local-file [
          remote-file-or-url [ result-file ] ]
          Uploads a local file to the server. Only the name of a single
          file can be given; wildcards (and group transfers) are not
          supported by HTTP protocol. If no remote filename is given, the
          file is sent with the same name as the local file, but with any
          pathname stripped.

   HTTP [ switches ] DELETE remote-file-or-url [ local-result-file ]
          Asks the server to delete the specified single file. If a
          result file is specified, it will contain any response data
          returned by the server.

   Note the limitations of HTTP protocol compared to (say) FTP or Kermit.
   There is no command for changing directories, no standard way to get
   file or directory lists, no way to transfer file groups by using
   wildcard notation, etc, and therefore no good way to (say) fetch all
   pages, descend through subdirectories, perform automatic updates, etc.
   There is no assurrance a connection will stay open and, as noted,
   there is no provision for data conversion between unlike platforms.
   The data's MIME headers can be used for postprocessing.

    2.2.3. HTTP Headers

   Each HTTP request and response contains a set of name/value pairs
   called headers. HTTP headers are specified in [178]RFC 2616. For
   example, an HTTP GET request for /index.html on www.columbia.edu
   contains the following headers:

  GET /index.html HTTP/1.1
  Host: www.columbia.edu:80
  User-agent: C-Kermit 8.0
  Authorization: Basic base64-encoded-username-password

   These might be followed by any others specified with a /HEADERS:
   switch:

  Accept: image/gif, image/x-xbitmap, image/jpeg, *.*
  Accept-Encoding: gzip
  Accept-Language: en
  Accept-Charset: iso-8859-1,utf-8
  Cookie: cookie-data

   The server sends back a short report about the file prior to sending
   the file contents. Example:

  HTTP/1.1 200 OK
  Date: Fri, 24 Aug 2001 21:09:39 GMT
  Server: Apache/1.3.4 (Unix)
  Last-Modified: Mon, 06 Aug 2001 21:16:13 GMT
  ETag: "1fa137-10d7-3b6f091d"
  Accept-Ranges: bytes
  Content-Length: 4311
  Content-Type: text/html

   If you want to have this information available to a Kermit script you
   can use the /ARRAY switch to have Kermit put it in array, one line per
   array element. Example:

  set exit warning off
  http open www.columbia.edu
  if fail exit 1 Can't reach server
  http /array:&a get /index.html
  if fail exit 1 Can't get file
  echo Header lines: \fdim(&a)
  for \%i 1 \fdim(&a) 1 {
      echo \%i. \&a[\%i]
  }

   Note that the "Date:" item is the current date and time; the
   "Last-Modifed:" item is the file's modification date and time. An
   example showing how to use this information is presented in
   [179]Section 8.13.7.

    2.2.4. Secure HTTP Connections

   SSL/TLS (Secure Sockets Layer / Transport Layer Security) is the
   protocol used to secure HTTP, SMTP, and other Internet applications.
   See the [180]C-Kermit Reference Section 5.4 for an introduction to
   SSL/TLS. To make a secure HTTP connection, you need:

    1. A secure client (a version of C-Kermit or Kermit 95 with SSL/TLS
       security built in). Type "check ssl" at the Kermit prompt to make
       sure you have it.
    2. A secure server to connect to.
    3. The CA Root Certificate used to authenticate the server to the
       client. (see [181]Section 15 of the security reference for an
       introduction to certificates).

   And you must make a connection to the secure HTTP port: service name
   HTTPS, port number 443 (as opposed to service HTTP, port 80). You can
   also make secure connections to other ports by including the /TLS or
   /SSL switch with the HTTP OPEN command, if the host supports SSL/TLS
   on the given port:

   The quality of the SSL/TLS connection depends on the cipher suite.
   There are several possibilities:

   Anonymous cipher suite:
          If an anonymous cipher suite is negotiated, the connection is
          encrypted but there is no authentication. This connection is
          subject to a Man-In-The-Middle (MITM) attack.

   X.509 certificate on the server:
          When you connect to certain secure servers, an X.509
          certificate is returned. This certificate is issued to a
          special hostname, something like www1.xyzcorp.com or
          wwws.xyzcorp.com (rather than the normal www.xyzcorp.com). It
          is signed by the host's Certificate Authority (CA). If the host
          certificate is configured on the client, it can be used to
          verify the certificate received from the server. If the
          certificate it verified as authentic, a check is made to ensure
          it has not expired and it was issued to the host you were
          attempting to connect to. If you had asked to connect to (say)
          www.xyzcorp.com but were given a certificate for
          www1.xyzcorp.com, you would be prompted for permission to
          continue.

          If the verification succeeded, the connection would be
          encrypted with one-way (server-to-client) authentication. This
          connection is not subject to a MITM attack.

          If a username and password are transmitted over this
          connection, they are not subject to interception. However, the
          standard risks associated with passing the password to the host
          for verification apply; for example, if the host has been
          compromised, the password will be compromised.

   X.509 client certificate:
          If a connection has been established with an X.509 server
          certificate, the server can ask the client to send a
          certificate of its own. This certificate must be verified
          against a CA Root certificate. The certificate itself (or
          subject info from the certificate) is used to determine the
          authorization for the client, and if successful, the username
          and password need not be sent to the server.

   Kerberos 5:
          Instead of using X.509 certifcates, Kerberos 5 can be used to
          perform the authentication and key exchange. In this situation,
          there is mutual authentication between the client and server.
          The Kerberos 5 principal is used by the server to look up the
          appropriate authorization data. There is no need to send
          username and password.

   An HTTP connection is made with the HTTP OPEN command:

   HTTP [ switches ] OPEN [ { /SSL, /TLS } ] host [ port ] 
          If /SSL or /TLS switches are included (these are synonyms), or
          if the service is HTTPS or the port is 443, a secure connection
          is attempted using the current authentication settings; see
          HELP SET AUTHENTICATION for details ([182]Section 6.2 of the
          security reference). If the no /SSL or /TLS switch is included
          but the port is 443 or the service is HTTPS, a secure
          connection is attempted. If an /SSL or /TLS switch is included
          but a port is not specified, an SSL/TLS connection is attempted
          on the default port (80).

   Certificates are covered in the separate [183]Kermit Security
   Reference for C-Kermit 8.0. You should let Kermit know to verify
   certificates with the SET AUTHENTICATION TLS command. For example:

   SET AUTHENTICATION TLS CRL-DIR directory
          Specifies a directory that contains certificate revocation
          files where each file is named by the hash of the certificate
          that has been revoked.

   SET AUTHENTICATION TLS CRL-FILE filename
          Specifies a file that contains a list of certificate
          revocations.

   SET AUTHENTICATION TLS VERIFY-DIR directory
          Specifies a directory that contains root CA certificate files
          used to verify the certificate chains presented by the peer.
          Each file is named by a hash of the certificate.

   SET AUTHENTICATION TLS VERIFY-FILE filename
          Specifies a file that contains root CA certificates to be used
          for verifying certificate chains.

   SET AUTHENTICATION TLS VERIFY OFF
          Tells Kermit not to require a certificate and accept any
          certificate that is presented regardless of whether it is
          valid.

   There are many other options; see the security document for details.

   Now suppose you need need to fetch the file denoted by the following
   URL:

  https://myuserid:mypassword@wwws.xyzcorp.com/clients/info/secret.html

   Once you have set up the handling of certificates as desired, you can
   use the following Kermit commands:

  http /user:myuserid /password:mypassword open www1.xyzcorp.com https
  if success {
      http get /clients/info/secret.html
      http close
  }

   As another example, let's say that you have a web form you need to
   populate with three fields: red,white and blue.

  <FORM ACTION="http://www.xyzcorp.com/cgi-bin/form.cgi" METHOD="POST">
  <INPUT NAME="Red">
  <INPUT NAME="White">
  <INPUT NAME="Blue">
  </FORM>

   You can handle this with the HTTP POST command. The data to be posted
   is stored in the local file data.txt.

  Red=seven stripes&White=six stripes&Blue=fifty stars

   and the response from the server will be stored into response.txt.

  http open www.xyzcorp.com http
  if success {
    http /array:c post data.txt /cgi-bin/form.cgi response.txt
    http close
  }

   In this scenario, the Common Gateway Interface (CGI) sends a response
   whether it succeeds or fails in a script-dependent manner. The script
   can either report success and enclose the response data; or it might
   send a 302 Found error which indicates that the "Location:" header
   should be used to determine the URL at which the data can be found.

    2.2.5. HTTP Variables

   \v(http_code)
          The HTTP protocol code number of the most recent server reply,
          e.g. 404 for "not found".

   \v(http_connected)
          1 when an HTTP connection is open, 0 when there is no HTTP
          connection.

   \v(http_host)
          If an HTTP connection is open, the hostname:port, e.g.
          www.columbia.edu:80; otherwise, empty.

   \v(http_message)
          Server error message, if any, from most recent HTTP command.

   \v(http_security)
          A list of the security parameters and values for the current
          connection, if any. Empty if the connection is not to a secure
          server, or there is no connection.

   To display all the HTTP variables at once, type SHOW VAR HTTP:

  C-Kermit> http open www.columbia.edu
  C-Kermit> http get lkjlkjlkjlkj 
  C-Kermit> sho var http
   \v(http_code) = 404
   \v(http_connected) = 1
   \v(http_host) = www.columbia.edu:80
   \v(http_message) = Not Found
   \v(http_security) = NULL
  C-Kermit>

    2.2.6. The HTTP Command-Line Personality

   If you invoke C-Kermit with the name "http" or "https", you can use a
   special set of HTTP-specific command-line options. You can do this by
   creating a symbolic linke "http" or "https" to the C-Kermit 8.0
   executable, or by having a separate copy of it called "http" or
   "https". Here's the usage message ("http -h"):

  Usage: ./http host [ options... ]
   -h             This message.
   -d             Debug to debug.log.
   -S             Stay (issue command prompt when done).
   -Y             Do not execute Kermit initialization file.
   -q             Quiet (suppress most messages).
   -u name        Username.
   -P password    Password.
   -g pathname    Get remote pathname.
   -p pathname    Put remote pathname.
   -H pathname    Head remote pathname.
   -l pathname    Local path for -g, -p, and -H.
   -z opt[=value] Security options...
      cert=file   Client certificate file
      certsok     Accept all certificates
      key=file    Client private key file
      secure      Use SSL
      verify=n    0 = none, 1 = peer , 2 = certificate required

   The "host" argument is the name of a Web host, e.g. www.columbia.edu.
   The action options are -p, -g, and -H. If you give an action option,
   Kermit does the action and then exits. If you give a host without an
   action option, Kermit makes an HTTP connection to the host and then
   gives you the C-Kermit prompt. Here's a simple example that fetches a
   publicly readable Web page:

  http www.columbia.edu -g kermit/index.html

   If you need to access a website for which a username and password are
   required, you can supply them on the command line with -u and -P. If
   you include a username but omit the password, Kermit prompts you for
   it:

  http www.columbia.edu -u olga -p kermit/index.html -l index.html
  Password:

   Note that when PUT'ing files to websites, you have to supply both the
   -p (remote pathname) and -l (local path) options.

   If your version of Kermit is built with SSL/TLS security, you can also
   use the -z option to make secure HTTP (https) connections.

   Finally, as noted in [184]Section 16, you can also give a URL instead
   of a host name and options.

   [ [185]Top ] [ [186]Contents ] [ [187]C-Kermit Home ] [ [188]Kermit
   Home ]
  __________________________________________________________________________

3. THE BUILT-IN FTP CLIENT

     3.1.  [189]Making and Managing FTP Connections
     3.2.  [190]Making Secure FTP Connections
     3.3.  [191]Setting FTP Preferences
     3.4.  [192]Managing Directories and Files
     3.5.  [193]Uploading Files With FTP
     3.6.  [194]Downloading Files With FTP
     3.7.  [195]Translating Character Sets
     3.8.  [196]FTP Command Shortcuts
     3.9.  [197]Dual Sessions
     3.10. [198]Automating FTP Sessions
     3.11. [199]Advanced FTP Protocol Features

   Earlier versions of C-Kermit and K95 included an FTP command, but it
   simply invoked an external FTP client. Now, by popular demand, Kermit
   includes its own built-in FTP client that offers the following
   advantages over traditional FTP clients (and its previous interface to
   them):

     * Any of Kermit's built-in [200]security methods can be used to
       establish and conduct secure FTP sessions with [201]FTP servers
       that support these methods. (Security modules can be subject to
       export restrictions.)
     * Kermit's FTP client uses "passive mode" by default to avoid
       blockage by firewalls and network address translators. Of course
       active mode can be chosen too when needed.
     * [202]Character sets can be translated as part of the transfer
       process even when the FTP server does not support character-set
       translation, including to/from the new Internet standard
       international character set, [203]Unicode UTF-8. This includes
       both the file's name and (for text files only) its contents.
     * All of C-Kermit's [204]file-selection mechanisms are available:
       size, date, name patterns and lists, exception lists, etc.
     * [205]Atomic file movement capabilities are provided (delete, move,
       or rename files automatically after successful transfer).
     * The correct file type, "ascii" (i.e. text) or binary, is chosen
       automatically for each file (explained in [206]Section 4), and any
       mixture of text and binary files can be sent in a single
       operation, even across platforms.
     * Update mode ("don't bother transferring files that didn't change
       since last time") and recovery (resumption of an interrupted
       transfer from the point of failure) are available in both
       directions.
     * When uploading files from UNIX to UNIX, the file's permissions can
       be preserved if desired.
     * Recursive directory-tree PUTs are supported between any two
       platforms that have tree-structured file systems. Recursive GETs
       are supported between like platforms if the server cooperates and
       between like or unlike platforms if the server supports MLSD
       ([207]Section 3.11).
     * When receiving files, all of Kermit's file collision actions are
       available: backup, update, refuse, rename, etc.
     * Multi-file transfers can be interrupted on a per-file basis,
       automatically skipping to the next file.
     * FTP sessions are [208]fully scriptable.
     * An entire FTP session (connect, login, CD, upload or download,
       logout) can be specified on the command line without using a
       script.
     * All of Kermit's logging options and formats are available to keep
       an accurate and complete record of each connection and file
       transfer, and to aid in troubleshooting.
     * All of Kermit's file-transfer display options are available
       (fullscreen, brief, CRT, serial, none).

   And best of all:
     * Kermit doesn't give you those annoying per-file prompts every time
       you start a multi-file transfer without remembering to give a
       "prompt" command first :-).

   [ [209]Top ] [ [210]FTP Top ] [ [211]FTP Client Overview ] [ [212]FTP
   Script Tutorial ] [ [213]C-Kermit Home ] [ [214]Kermit Home ]
     _________________________________________________________________

  3.1. Making and Managing FTP Connections

   Each copy of Kermit can have one FTP connection open at a time. FTP
   connections are independent of regular terminal connections; a
   terminal connection (serial or network via SET LINE, DIAL, SET HOST,
   TELNET, etc) may be, but need not be, open at the same time as an FTP
   connection, and terminal connections can also be closed, and new
   connections opened, without interfering with the FTP connection (and
   vice versa). Thus, for example, Kermit can have an FTP connection and
   a TELNET connection open to the same host simultaneously, using the
   TELNET connection (e.g.) to send mail or take other desired actions as
   various FTP actions complete. Of course, each copy of Kermit can do
   only one thing at a time, so it can't (for example) transfer a file
   with FTP and another file with Kermit protocol simultaneously.

   A Kermit FTP session can be established by [215]command-line options,
   by [216]URL, or by [217]interactive commands.

    3.1.1. Kermit Command-Line Options for FTP

   The new command-line option '-9' (sorry, we're out of letters) can be
   used when starting C-Kermit, telling it to make an FTP connection:

  kermit -9 hostname

   or if a non-default FTP port is needed:

  kermit -9 hostname:port

   You can also specify the username on the command line with the -M ("My
   User ID") option that was already there for other connection types:

  kermit -9 hostname -M olga

   If you specify the username on the command line, Kermit uses it when
   making the connection and does not prompt you for it (but it does
   prompt you for the password if one is required).

   Once the connection is made, you get the regular Kermit prompt, and
   can give interactive commands such as the ones described below. When
   you give a BYE command, Kermit closes the session and exits, just as a
   regular FTP client would do. If you don't want Kermit to exit when you
   give a BYE command, include the -S ("Stay") option on the command
   line.

   Other Kermit command-line options that are not specific to non-FTP
   connections should affect the FTP session in the expected ways; for
   example, -i and -T force binary and text mode transfers, respectively.

   File transfers can not be initiated on the "kermit -9" command line;
   for that you need to use Kermit's FTP personality (next section) or
   you can use URLs ([218]Section 3.1.3).
     _________________________________________________________________

    3.1.2. The FTP Command-Line Personality

   If you want to replace your regular FTP client with C-Kermit, you can
   make a link called "ftp" to the C-Kermit binary (or you can store a
   copy of the C-Kermit binary under the name "ftp"). When C-Kermit is
   invoked with a program name of "ftp" (or "FTP", case doesn't matter),
   it assumes the command-line personality of the regular FTP client:

  ftp [ options ] hostname [ port ]

   In this case the options are like those of a regular FTP client:

  -d  Debug: enables debug messages and creates a debug.log file.
  -n  No autologin: Kermit should not send your user ID automatically.
  -t  Packet trace: accepted but is treated the same as -d.
  -v  Verbose: accepted but ignored (operation is verbose by default).
  -i  Not interactive: accepted but ignored.

   and the hostname can also be a URL (explained in [219]Section 3.1.3).
   To specify a non-default TCP port for the FTP server, include the port
   number or name after the hostname.

   There are also some bonus options that allow you to execute an entire
   FTP session from the shell command line, as long as you don't include
   the -n option. These are not available with regular FTP clients, and
   at least one of these options (-g) conflicts with UNIX ftp (where -g
   means "no globbing", which does not apply to Kermit), and some of them
   (like the options above) also conflict with regular Kermit
   command-line options:

  -m mode      = "passive" (default) or "active"
  -Y            Don't execute the Kermit initialization file [1]
  -q            Quiet, suppresses all but error messages [1]
  -S            Stay, don't exit automatically [1]
  -A            Autologin anonymously [2]
  -u name       Username for autologin [2] (synonym: -M [1])
  -P password   Password for autologin (see cautions below) [2]
  -D directory  cd after autologin [2]
  -b            Binary mode [2]
  -a            Text ("ascii") mode [2] (synonym: -T [1])
  -R            Recursive (works with -p) [4]
  -p files      Files to put (upload) after autologin [2] (synonym: -s [1])
  -g files      Files to get (download) after autologin [3]

   [1] Same as Kermit, not available in regular FTP clients.
   [2] Conflicts with Kermit, not available in regular FTP clients.
   [3] Same as Kermit, conflicts with regular FTP clients.
   [4] Conflicts with Kermit, available in some FTP clients.

   Fancier options such as restart, character-set translation, filename
   collision selection, automatic move/rename/delete, etc, are not
   available from the command line; for these you can use the commands
   described in the following sections. The -R option might also work
   with -g (GET) but that depends on the server.

   The following security options are also available, explained in
   [220]Section 3.2:

  -k realm      Kerberos 4 realm [4]
  -f            Kerberos 5 credentials forwarding [4]
  -x            autoencryption mode [4]
  -c cipher     SRP cipher type [4]
  -H hash       SRP encryption hash [4]
  -z option     Security options [4]

   If you include -A or specify a name of "anonymous" or "ftp", you are
   logged in anonymously and, in the absence of -P, Kermit automatically
   supplies a password of "user@host", where "user" is your local user
   ID, and "host" is the hostname of the computer where Kermit is
   running. If you do not include -p or -g, Kermit enters command mode so
   you can type commands or execute them from a script.

   If you include -p or -g, Kermit attempts to transfer the specified
   files and then exits automatically at the end of the transfer unless
   you also included -S (Stay). It uses the "brief" file transfer display
   (one line per file) unless you include the -q option to suppress it.

   When uploading files with -p, Kermit switches automatically between
   text and binary mode for each file.

   When downloading, you can either specify a particular mode (text or
   binary) to be used for all the files, or you can let Kermit select the
   type for each file automatically, based on its name (see [221]Sections
   3.5 and [222]3.6 for greater detail). In UNIX be sure to quote any
   wildcard characters to prevent the shell from expanding them, as shown
   in the examples just below. Filename collisions are handled according
   Kermit's FILE COLLISION setting (if specified in your Kermit
   customization file; otherwise the default, which is BACKUP).

   It should go without saying that the -P option should be used with
   caution. In addition to the well-known risks of transmitting plaintext
   passwords over the Internet, in this case the password also echos to
   the screen if you type it, and can be seen in ps and w listings that
   show the user's currently active command and command-line arguments.
   Thus command-line FTP sessions are most appropriate for secure or
   anonymous connections (those that do not require passwords).

   Here's an example in which you download the latest C-Kermit "tarball"
   from the Columbia University FTP archive:

  ftp -A kermit.columbia.edu -bg kermit/archives/ckermit.tar.gz

   This assumes that "ftp" is a symbolic link to C-Kermit. It logs you in
   anonymously and gets the ckermit.tar.gz file in binary mode from the
   kermit/archives directory.

   Here's a slightly more ambitious example that illustrates CD'ing to
   the desired server directory to get a group of files in text mode (in
   this case the C-Kermit source files):

  ftp -A kermit.columbia.edu -D kermit/f -ag "ck[cuw]*.[cwh]" makefile

   In this case we CD to the kermit/f directory so we don't have to
   include it in each file specification, and we quote the ck[cuw]*.[cwh]
   specification so the shell doesn't expand it, since we have to pass it
   as-is to the server. Note also that the quotes don't go around the
   entire file list; only around each file specification that needs to be
   quoted.

   Here's one more example, that uploads a debug log file in binary mode
   to the Kermit incoming directory (as we might ask you to do when
   following up on a problem report):

  ftp -A kermit.columbia.edu -D kermit/incoming -bp debug.log

   In this case the -D option is required to tell the server where to put
   the incoming file.

   Unless the -Y option is included, your Kermit initialization file
   (.mykermrc in UNIX, K95.INI in Windows) is executed before the command
   line options, so you can set any FTP-related preferences there, as
   described in the subsequent sections.
     _________________________________________________________________

    3.1.3. The FTP URL Interpreter

   If Kermit is invoked with either its regular personality (as "kermit")
          or its FTP personality (as "ftp"), you can also give a URL
          (Universal Resource Locator) instead of a hostname and options,
          with or without a username and password:
          ftp ftp://user:password@host/path
          ftp ftp://user@host/path
          ftp ftp://@host/path   (or ftp://:@host/path)
          ftp ftp://host/path
          kermit ftp://host/path

   If the FTP personality is used, the service must be "ftp". In all
   cases, a hostname or address must be included. If a user is included
   but no password, you are prompted for the password. If a path
   (filename) is included:
     * If "@" is included without a user, Kermit prompts for the username
       and password.
     * If no user and no "@" are included, "anonymous" is used.
     * GET is assumed.

   If no path (and no action options) are included, an interactive FTP
          session is started, as in this example:
          ftp ftp://kermit.columbia.edu

   If a path is included, but a username is not included, "anonymous" is
   used and an appropriate user@host password is supplied automatically.
   If authentication is successful, Kermit attempts to GET the file
   indicated by the path or, if the path is the name of a directory, it
   asks the server for a directory listing. In both cases, Kermit
   disconnects from the server and exits after the operation is complete
   (unless you have included the -S option on the command line).

   Here's an example that gets a listing of the Kermit directory at the
          Kermit ftp site:
          ftp ftp://kermit.columbia.edu/kermit/

   This example gets the top-level READ.ME file from the same directory:
          ftp ftp://kermit.columbia.edu/kermit/READ.ME

   Here's the same example, but requesting a text-mode transfer:
          ftp -T ftp://kermit.columbia.edu/kermit/READ.ME
          This illustrates that you can mix command-line options and URLs
          if you desire.

   Here's an example that logs in as a (fictitious) real user to get a
          file:
          ftp ftp://olga@ftp.xyzcorp.com/resume.txt
          The password is not included, so Kermit prompts for it.

   This scheme allows Kermit to be used as the FTP helper of other
   applications, such as Web browsers, with all its advantages over other
   FTP clients (especially the ones that are built in to most Web
   browsers), e.g. that it can be given wildcards, and it can pick text
   and binary mode automatically for each file.

   HINT: suppose somebody sends you an FTP URL in email, or you see it in
   some text. If your terminal screen supports copy/paste, copy the url,
   and then at the shell prompt type "kermit", a space, and then paste
   the URL, e.g.:

  $ kermit ftp://alpha.greenie.net/pub/mgetty/source/1.1/mgetty1.1.27-O

   "$ is the shell prompt; the part you type is underlined, the rest is
   pasted in. Kermit does the rest.
     _________________________________________________________________

    3.1.4. Interactive FTP Session Establishment

   As you read this and the following sections, bear in mind that any
   command that can be given at the prompt can also be used in a script
   program. Kermit's script programming language is the same as its
   interactive command language. [223]CLICK HERE if you would like to
   learn a bit more about script writing.

   An FTP session is established with the FTP OPEN command:

   FTP [ OPEN ] [ { /SSL, /TLS } ] hostname [ switches ] [ port ]
          Opens an FTP connection to the given host on the given port
          and, if FTP AUTOLOGIN is ON, also logs you in to the server,
          prompting for username and password if necessary. If no port is
          specified, the regular FTP protocol port (21) is used. The OPEN
          keyword is optional (unless the hostname conflicts with one of
          the FTP command keywords, which you can list by typing "ftp
          ?").

   The hostname can be an IP host name, numeric IP address, or if you
   have a network directory active (SET NETWORK DIRECTORY; see Chapter 6
   of [224]Using C-Kermit), an entry name in the directory. In the latter
   case, if the given hostname matches exactly one entry, the associated
   name or address is used; if it matches more than one, Kermit cycles
   through them until one is found that can be opened; if it matches
   none, then the hostname is used as-is. If a directory is active but
   you want to bypass directory lookup, include an "=" sign at the
   beginning of the hostname, and/or use a numeric IP address.

   When an FTP connection is opened, the default file-transfer mode is
   set to binary if the client and server platforms are alike (e.g. both
   of them are some kind of UNIX), and to text ("ascii") if they are not
   alike. This has no particular effect for uploading since Kermit
   automatically switches between text and binary mode for each file, but
   might be important for downloading. The connection is also set to
   Stream mode and File structure. Record- or page-oriented file
   transfers are not supported by C-Kermit's FTP client.

   The optional FTP OPEN switches are:

   /ANONYMOUS
          Logs you in anonymously, automatically supplying username
          "anonymous" and user@host as the password, based on your local
          user and host names.

   /NOLOGIN

          Overrides SET FTP AUTOLOGIN ON for this connection only.

   /USER:name
          Uses the given username to log you in, thus avoiding the Name:
          prompt.
          Overrides SET FTP AUTOLOGIN OFF for this connection only.

   /PASSWORD:text
          Uses the given text as your password, thus avoiding the
          Password: prompt. This switch is not recommended for use in
          script files, which would be a security risk.

   /ACCOUNT:text
          Uses the given text as your account (or secondary password,
          depending on the requirements of the server; most servers do
          not require or accept an account name). If an account is not
          supplied, you are not prompted for one.

   /PASSIVE
          Opens the connection in passive mode. Passive mode is the
          default in Kermit's FTP client, unlike in most others, since it
          works better through firewalls. The /PASSIVE and /ACTIVE
          switches apply only to the connection that is being opened, and
          do not affect the global FTP PASSIVE-MODE setting.

   /ACTIVE
          Opens the connection in active mode. Use this switch if the
          server does not support passive mode, or use the command SET
          FTP PASSIVE-MODE OFF.

   /NOINIT
          Added in C-Kermit 8.0.201.   Tells C-Kermit not to send REST,
          STRU, FEAT, and MODE commands to the server when the connection
          is opened, since these have been reported to cause confusion in
          certain servers.

   When a username or password is missing, a prompt is issued at the
   controlling terminal and you must type the response; the response can
   not be scripted. Use the switches to avoid prompts, or one of the
   secure authentication methods described in the next section, or see
   [225]SET FTP AUTOLOGIN and the [226]FTP USER and similar commands
   described later in this section.

   Examples:

  ftp open kermit.columbia.edu /anonymous  ; Open and log in anonymously
  ftp kermit.columbia.edu /anonymous       ; The OPEN keyword can be omitted
  ftp xyzcorp.com                          ; Open and maybe prompt for username
  ftp xyzcorp.com /user:olga               ; Open and log in as olga
  ftp testing.abccorp.com 449              ; Specify a special TCP port number
  ftp testing.abccorp.com /user:olaf /password:secret 449

   The FTP OPEN command succeeds if a connection was opened to the server
   (even if the given username and password were not valid) and fails
   otherwise (see [227]Section 3.8 for details).

   When your FTP session is complete, you can terminate it as follows:

   FTP BYE
          Closes the FTP connection if one was open. The FTP prefix can
          be omitted if no other connection is open at the same time (see
          [228]Section 3.8 for details). If a connection log is active,
          an FTP record is written to it. If Kermit was started with the
          -9 command-line option or with its FTP command-line
          personality, and the -S (Stay) option was not given, AND there
          is no other active connection, the FTP BYE command also exits,
          just as it does on a regular FTP client. Synonyms: FTP CLOSE,
          FTP QUIT (but if the FTP prefix is omitted from QUIT, this
          becomes the regular Kermit QUIT command, which is equivalent to
          EXIT; i.e. it closes the connection and exits from Kermit).

   The following commands can be used to achieve greater control over the
   connection and login process:

   SET FTP ANONYMOUS-PASSWORD text
          Allows you to choose the password text to be sent automatically
          by Kermit when you open an FTP connection with the /ANONYMOUS
          switch.

   SET FTP AUTOLOGIN { ON, OFF }
          If you give this command prior to opening an FTP connection, it
          controls whether Kermit tries to log you in automatically as
          part of the connection process. Normally ON, which means the
          username and password are sent automatically (and prompted for
          if they are not yet known). When OFF, FTP OPEN connects to the
          server without logging in. OFF is equivalent to the -n
          command-line option when using Kermit's FTP command-line
          personality.

   FTP USER name [ password [ account ] ]
          Used to log in to an FTP server to which a connection has been
          made without autologin, or when autologin failed. If the
          password is furnished on the command line, it is used;
          otherwise you are prompted for a password. An account may also
          be furnished if required by the server; it is not required by
          Kermit and is not prompted for if omitted. Synonyms: USER, FTP
          LOGIN.

   FTP ACCOUNT text
          Sends an account name to a server that supports accounts. If
          the server does not support accounts, an error response occurs.
          If the server does support accounts, the account is accepted if
          it is valid and rejected if it is not. The account might be
          used for charging purposes or it might be a secondary password,
          or it might be used for any other purpose, such as an access
          password for a particular disk. Servers that support accounts
          might or might not allow or require the account to be sent
          prior to login; usually it is sent after login, if at all.
          Synonym: ACCOUNT.

   Example:

set ftp autologin off                  ; One thing at a time please
ftp xyzcorp.com                        ; Try to make the connection
if fail exit 1 FTP connection failed   ; Check that it was made
ftp user olga secret                   ; Now log in to the server
if fail exit 1 FTP login failed        ; Check that it worked
ftp account 103896854                  ; Login OK - send account
if fail echo WARNING - FTP ACCT failed ; Warn if problem
...                                    ; (have session here)
bye                                    ; Log out and disconnect

   The following commands are used to control or get information about
   the FTP connection. Any particular FTP server does not necessarily
   support all of them.

   FTP RESET
          Terminates a user session but leaves the connection open,
          allowing a new login via FTP USER.

   FTP IDLE [ number ]
          Most FTP servers automatically log you out and and disconnect
          your session if there has been no activity for a certain amount
          of time. Use this command to ask the server to set its idle
          limit to the given number of seconds. Omit the number to ask
          the server to inform you of its current idle limit.

   FTP STATUS [ filename ]
          Asks the FTP server to send information about the current
          session. The result is a free-format report that might include
          server identification, username and login time, FTP protocol
          settings, and file-transfer statistics. If a filename is given,
          the server is supposed to send detailed information about the
          file.

   FTP SYSTEM
          Asks the FTP server to identify its operating system (Listed in
          Internet Assigned Numbers, Operating System Names). Examples:
          UNIX, VMS, VM/CMS, WINDOWS-NT. Unfortunately many variations
          are allowed (e.g. LINUX-2.0, LINUX-2.2, FREEBSD, ULTRIX, etc,
          instead of UNIX; WINDOWS-NT-3, WINDOWS-NT-3.5, WINDOWS-NT-3.51,
          WINDOWS-NT-4, etc). The report might also include other
          information like "Type L8", "Type I", or "Type A", indicating
          the file-transfer mode.

   FTP HELP [ keyword [ keyword [ ... ] ]
          Asks the server to list the commands it supports. The response
          is usually cryptic, listing FTP command mnemonics, not the
          commands used by the client (since the server has no way of
          knowing anything about the client's user interface). For
          example, the PUT command is STOR in FTP protocol. If a keyword
          is given, which should be an FTP protocol command,
          slightly-more- detailed help is given about the corresponding
          command (if the FTP server supports this feature). Examples:
          "ftp help", "ftp help stor".

   FTP SITE text
          (Advanced) Sends an FTP SITE (site-specific) command. Usually
          this means that the FTP server is asked to run an external
          command with the given arguments. You might be able to find out
          what SITE commands are available by sending "ftp help site" to
          the server, but in general the availability of and response to
          SITE commands is (not surprisingly) site specific.

   FTP QUOTE text
          (Advanced) Sends an FTP command in FTP protocol format. Use
          this command to send commands to the server that the FTP client
          might not know about.

   SHOW FTP
          Lists client (Kermit) FTP settings and information. Also SHOW
          CONNECTION, SHOW COMMUNICATIONS.

   HELP FTP [ keyword ]
          Asks Kermit to list and describe its built-in FTP commands.

   HELP SET FTP [ keyword ]
          Asks Kermit to list and describe its built-in SET FTP commands.

   [ [229]Top ] [ [230]FTP Top ] [ [231]C-Kermit Home ] [ [232]Kermit
   Home ]
     _________________________________________________________________

  3.2. Making Secure FTP Connections

   Also see: [233]Accessing IBM Information Exchange with Kermit.

   In the previous section, you can see several examples of traditional
   insecure authentication: username and password sent across the network
   in clear text. Of course this is bad practice on at least two counts:
   (1) storing passwords in files (such as script files) gives access to
   the target systems to anybody who can obtain read access to your
   scripts; and (2) sending this information over the network leaves it
   open to interception by network sniffers or compromised hosts.

   Because of the increasing need for security on the Internet, FTP
   servers are beginning to appear that offer secure forms of
   authentication, in which no information is sent over the network that
   would allow anyone who intercepts it to usurp your identity and gain
   your access rights.

   Kermit provides an equivalent form of FTP security for each type of
   IETF standard security implemented in Telnet. These include
   GSSAPI-KERBEROS5, KERBEROS4, Secure Remote Password (SRP), and
   Transport Layer Security (SSL and TLS). It does not presently include
   SSL tunneling nor any form of SSH v1 or v2. When Kermit is built with
   the necessary libraries, secure FTP connections are attempted by
   default, in which all connections are authenticated and the command
   and data channels are private.

   The use of authentication and encryption for FTP connections can be
   adjusted with the commands listed below, which are available only if
   your version of Kermit was built with the corresponding security
   options and libraries:

   SET FTP AUTHTYPE { AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS }
          Specifies an ordered list of authentication methods to be
          attempted when AUTOAUTHENTICATION is ON. The default list is:
          GSSAPI-KRB5, SRP, KERBEROS_V4, TLS, SSL. If none of the
          selected methods are supported by the server, an insecure login
          is used as a fallback. Note, by the way, that SSL or TLS can be
          used to secure an anonymous connection.

   SET FTP AUTOAUTHENTICATION { ON, OFF }
          Tells whether authentication should be negotiated by the FTP
          OPEN command. Default is ON. Use SET FTP AUTOAUTHENTICATION OFF
          to force a clear-text, unencrypted connection to FTP servers
          (such as the one at the Kermit FTP site) that normally would
          try to negotiate secure authentication and encryption.

   SET FTP AUTOENCRYPTION { ON, OFF }
          Tells whether encryption (privacy) should be negotiated by the
          FTP OPEN command, which can happen only if secure
          authentication is also negotiated. Default is ON.

   SET FTP AUTOLOGIN { ON, OFF }
          Tells Kermit whether to try logging in automatically when you
          make an FTP connection, as opposed to letting you do it "by
          hand" with the FTP USER command.

   SET FTP COMMAND-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE
          }
          Determines the level of protection applied to the command
          channel:

  CLEAR         Data is sent in plaintext and not protected against tampering.
  CONFIDENTIAL  Data is encrypted but not protected against tampering.
  PRIVATE       Data is encrypted and is protected against tampering.
  SAFE          Data is sent in plaintext but protected against tampering.

          The default is PRIVATE.

   SET FTP CREDENTIAL-FORWARDING { ON, OFF }
          Tells whether end-user credentials are to be forwarded to the
          server if supported by the authentication method (GSSAPI-KRB5
          only). This is often required to allow access to distributed
          file systems (e.g. AFS.)

   SET FTP DATA-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE }
          Tells what level of protection is applied to subsequent data
          channels. The meanings of the protection-level keywords are the
          same as for SET FTP COMMAND-PROTECTION-LEVEL. The default is
          PRIVATE.

   SET FTP SRP CIPHER name
          Specifies the cipher to be used for encryption when SRP
          authentication is in use. The list of possible choices is
          computed based on the capabilities of the local SRP library and
          includes NONE plus zero or more of the following:

  BLOWFISH_ECB        CAST5_ECB          DES_ECB          DES3_ECB
  BLOWFISH_CBC        CAST5_CBC          DES_CBC          DES3_CBC
  BLOWFISH_CFB64      CAST5_CFB64        DES_CFB64        DES3_CFB64
  BLOWFISH_OFB64      CAST5_OFB64        DES_OFB64        DES3_OFB64

          The default is DES3_ECB.

   SET FTP SRP HASH name
          Specifies the hash to be used for data protection when SRP
          authentication is in use. The choices are MD5 and SHA. The
          default is SHA.

   Command-line options:

   -k name
          Specifies the realm to be used with Kerberos 4 authentication
          (= SET AUTH K4 REALM name).

   -f
          Enables forwarding of Kerberos 5 credentials to the host when
          using GSSAPI authentication (= SET AUTH K5 FORWARDABLE ON).

   -x
          Enables autoencryption (= SET FTP AUTOENCRYPTION ON).

   -c cipher
          Specifies the kind of cipher to be used for encryption with SRP
          authentication. Equivalent to SET FTP SRP CIPHER, with the same
          choices. If this option is not given, CAST5_CBC is used.

   -H hash
          Specifies the hash to be used for encryption with SRP
          authentication. Equivalent to SET FTP SRP HASH, with the same
          choices. If this option is not given, SHA is used.

   -z debug
          Turns on SSL/TLS debugging.

   -z secure
          Requires secure connection.

   -z certsok
          Says to accept all certificates without checking validity.

   -z verify=n
          Sets certificate verification mode to the given number, n:
            0 = no verification
            1 = verify certificate if presented
            2 = require verification of certificate

   -z cert=filename
          Specifies a file containing a client certificate to be
          presented to the FTP server.

   -z key=filename
          Specifies a file containing a private key matching the client
          certificate.

   -z !krb4
          (nokrb4) Disables the use of Kerberos 4.

   -z !gss
   -z nogss
          Disables the use of GSSAPI - Kerberos 5.

   -z !srp
   -z nosrp
          Disables use of SRP.

   -z !ssl
   -z nossl
          Disables the use of SSL.

   -z !tls
   -z notls
          Disables the use of TLS.

   Caution: If your FTP connection is secured via AUTH TLS, it is not
   possible to interrupt a file transfer. This is a limitation of all
   known FTP servers that support AUTH TLS.

   Note that when using certain security methods, such as SSL or TLS, you
   may be prompted to confirm or verify certain actions or conditions,
   for example, whether to accept self-signed certificates. This can
   interfere with unattended operation of scripts; see [234]Section 3.10.

   [ [235]Top ] [ [236]FTP Top ] [ [237]C-Kermit Home ] [ [238]Kermit
   Home ]
     _________________________________________________________________

   3.3. Setting FTP Preferences FTP preferences can be set globally and
   persistently with the commands in the following sections; many of
   these can also be overridden on a per-command basis with switches that
   have the same name.

    3.3.1. Logs, Messages, and Other Feedback

   You can control the amount of feedback received from your FTP session
   with the commands in this section. First, you can create a log of your
   FTP transfers with the following commands:

   SET TRANSACTION-LOG { VERBOSE, FTP, BRIEF }
          Selects the log format. VERBOSE is the default, and is
          described in [239]the manual. FTP chooses a WU-FTPD format, the
          same as is used by the popular FTP server. BRIEF creates
          per-file records in comma-separated-list format. For greater
          detail, see [240]Section 4.17 of the [241]C-Kermit 7.0 Update
          Notes.

   LOG TRANSACTIONS filename
          Records FTP (or Kermit, or any other protocol) uploads and
          downloads in the given file using the format selected by the
          most recent SET TRANSACTION-LOG command, if any, or else the
          default format.

   FTP screen messages and displays are controlled by the following
   commands:

   SET TRANSFER DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE, OFF }
          FTP transfers use Kermit's normal file-transfer display styles.
          Use this command to choose the desired format; the default on
          most platforms is FULLSCREEN. The display is automatically
          disabled if Kermit is running in the background or in batch.
          BRIEF is always used for command-line initiated transfers
          (unless suppressed by -q). While a file-transfer is in
          progress, you can interrupt it in the normal Kermit way by
          typing one of the following keys or key combinations:
            X - Cancel current file but go on to the next one (if any).
            Z - Cancel the entire transfer.   Ctrl-L or Ctrl-W - Refresh
          the file-transfer display (if any).

   SET FTP DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE, OFF }
          Like SET TRANSFER DISPLAY, but applies only to FTP connections,
          and does not affect Kermit- or other protocol file transfers.

   SET QUIET { ON, OFF }
          This command applies to Kermit in general, not just FTP. OFF by
          default; when ON, it surpresses most messages from most
          commands as well as the file-transfer display.

   SET FTP PROGRESS-MESSAGES { ON, OFF }
          Tells whether Kermit should print locally-generated feedback
          messages for each non-file-transfer command. ON by default.

   SET FTP VERBOSE-MODE { ON, OFF }
          Tells whether to display all responses from the FTP server. OFF
          by default. This shows all responses to all commands, except
          when the file-transfer display is active, and unless you have
          SET QUIET ON. When OFF, responses are shown only for commands
          such as FTP PWD whose purpose is to display a response.

   SET FTP DEBUG { ON, OFF }
          Tells whether local client debugging information should be
          displayed. OFF by default. When ON, the commands that are sent
          to the server are shown, as well as its responses (even if
          VERBOSE-MODE is OFF), plus additional informational messages
          are printed regarding the progress of secure operations. Also,
          the temporary file created by the [242]MGET command is not
          deleted so you can see what's in it.

   Set all of these to OFF when silent running is desired.

    3.3.2. Operational Preferences

   FTP DISABLE new-protocol-feature-name
   FTP ENABLE new-protocol-feature-name
          Explained in [243]Section 3.11.

   SET FTP AUTOLOGIN { ON, OFF }
          If you give this command prior to opening an FTP connection, it
          controls whether Kermit tries to log you in automatically as
          part of the connection process. Normally ON, which means the
          username and password are sent automatically (and prompted for
          if they are not yet known). When OFF, FTP OPEN connects to the
          server without logging in. OFF is equivalent to the -n
          command-line option when using Kermit's FTP command-line
          personality. See [244]Section 3.1.4 for usage.

   SET FTP PASSIVE-MODE { ON, OFF }
          ON by default, to avoid random TCP port assignment for data
          connections, which can prevent FTP protocol from working
          through firewalls and network address translators (for more on
          these topics, see the [245]Kermit security reference. Set to
          OFF in case the FTP server does not support passive mode, or in
          case the client has problems with it (it has been observed, for
          example, that when using passive mode, the SCO XENIX 2.3.4
          TCP/IP stack hangs in the connect() call forever). Synonyms:
          PASSIVE [ ON ], PASSIVE OFF, PASV [ ON ], PASV OFF.

   SET FTP SEND-PORT-COMMANDS { ON, OFF }
          This command determines whether the FTP client sends a new PORT
          command to the server when accepting incoming data connections
          (as when not using passive mode.) When PASSIVE-MODE is OFF and
          SET SEND-PORT is OFF, the port that was originally specified is
          reused. This is the default behavior for normal FTP clients but
          it is not compatible with many firewalls.

   SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
          Whether to translate character sets when transferring files
          with FTP (explained in [246]Section 3.7). OFF by default.

   SET FTP SERVER-CHARACTER-SET name
          Tells Kermit the character set used by the FTP server, UTF-8 by
          default ([247]Section 3.7).

   SET FTP SERVER-TIME-OFFSET delta-time
          Tells Kermit to apply the given [248]delta time to file
          timestamps provided by the server for its files; for use when
          (for example) the server does not have its timezone set
          correctly.

   SET FTP ERROR-ACTION { PROCEED, QUIT }
          When transferring a group of files with FTP, and an error
          occurs with one of the files, Kermit normally goes on the next
          file. Use SET FTP ERROR-ACTION to QUIT to make Kermit stop the
          transfer immediately and fail if an error occurs with any
          single file in the group. Example: you have given Kermit a list
          of files to send, and one of the files can not be found, or
          read permission is denied. Note that cancelling a file by
          typing 'X' during transfer is not considered an error (if you
          want to cancel the entire transfer, type 'Z' or Ctrl-C).

   SET FTP PERMISSIONS { AUTO, ON, OFF }
          When uploading files with PUT or MPUT, this tells whether
          Kermit should send each file's permissions. The default is OFF,
          which means not to send permissions, in which case the uploaded
          file's permissions are set by the FTP server according to its
          own criteria. ON means to send them, AUTO means to send them
          only if the client (Kermit) and server are on like platforms
          (e.g. both UNIX). This command has no effect when downloading,
          since the FTP protocol does not include a way for the server to
          inform the client of a file's permissions. Also see [249]FTP
          PUT /PERMISSIONS. Note that setting permissions after uploading
          is likely to work (correctly or at all) only when the client
          and server platforms are alike (e.g. both of them are some form
          of UNIX). Also note that Windows files don't have permissions.
          Also see [250]FTP CHMOD.

   SET FTP DATES { ON, OFF }
          When downloading files with GET or MGET, this tells whether
          Kermit should try to set the received file's date from the
          server's date. FTP DATES is ON by default. Note, however, that
          FTP protocol does not allow date preservation when uploading.
          So at best, SET FTP DATES ON can work only when downloading,
          and then only when the server agrees to furnish file dates.

   SET FTP FILENAMES { AUTO, CONVERTED, LITERAL }
          When uploading (sending) files, this tells whether to convert
          outbound filenames to "common form". This means allowing only
          one period in a name, uppercasing any lowercase letters,
          replacing spaces by underscores, etc. AUTOMATIC is the default,
          meaning LITERAL when client and server are the same type of
          system (e.g. UNIX) and CONVERTED otherwise. Special case: if
          the setting is AUTOMATIC and the client is not UNIX and the
          server identifies itself as UNIX, Kermit uses a less-strict
          form of conversion, in which lowercase letters are not
          uppercased and the filename can contain any number of periods,
          but spaces are still converted to underscore. When receiving,
          conversion generally means to change all-uppercase names to
          lowercase and spaces to underscore.

   SET FTP UNIQUE-SERVER-NAMES { ON, OFF }
          Applies only to uploads. Tells the server to create new, unique
          names for incoming files that have the same names as existing
          files. OFF by default, in which case the server overwrites
          existing files with new files of the same name. When ON, the
          server uses its own built-in method for creating new names for
          incoming files; for example, appending a period (.) and a
          number to the name. CAUTION: Use this option only if you do not
          need to refer to the file after it is uploaded, since FTP
          protocol provides no mechanism for the client to find out what
          name was assigned by the server.

   SET FTP COLLISION { ... }
          When downloading, what to do if an incoming file has the same
          name as an existing file. Options are the same as for SET FILE
          COLLISION. If this command is not given, Kermit's regular FILE
          COLLISION setting is used. If this command is given, it
          overrides the FILE COLLISION setting for FTP transfers only.
          See [251]Section 3.6.2 for details.

   SET FTP TYPE { TEXT, BINARY, TENEX }
          Changes the default transfer mode. When sending (uploading)
          files, this command has no effect unless you disable automatic
          text/binary mode switching ([252]Section 4) with SET FILE SCAN
          OFF or SET TRANSFER MODE MANUAL. When receiving (downloading)
          files, this command establishes the transfer mode to be used
          when a filename does not match any of Kermit's text or binary
          filename patterns, unless you use SET FTP
          GET-FILETYPE-SWITCHING or SET TRANSFER MODE MANUAL to disable
          automatic switching, in which case, this command establishes
          the transfer mode for all downloaded files. In all cases,
          however, the FTP TYPE can be overridden in any GET or PUT
          command by including a /TEXT (/ASCII), /BINARY, or /TENEX
          switch. The FTP TYPE is independent of the Kermit FILE TYPE
          setting. TENEX is used for sending 8-bit binary files to 36-bit
          platforms such as TOPS-10, TOPS-20, and TENEX, and getting them
          back again. Synonym: ASCII = TEXT. Note: there is also an FTP
          TYPE command, which does what SET FTP TYPE does but also sends
          a TYPE command to the server immediately if the given type is
          different from the current one.

   If you want want specific FTP preference settings to be in effect for
   all your Kermit FTP sessions, put the desired SET FTP commands in your
   Kermit customization file (~/.mykermrc in UNIX, K95CUSTOM.INI in
   Windows).

   [ [253]Top ] [ [254]FTP Top ] [ [255]C-Kermit Home ] [ [256]Kermit
   Home ]
     _________________________________________________________________

  3.4. Managing Directories and Files

   In Kermit, commands for directory and file management can refer to:

     * The local computer
     * A remote computer when you have a connection to a Kermit server or
       IKSD.
     * A remote computer when you have a connection to an FTP server.

   (There can also be an HTTP connection, but the commands in this
   section don't apply to HTTP connections.)

   Thus in general, each such command comes in three forms:

    1. With no prefix in C-Kermit 8.0.200, it refers to the local
       computer (CD, DIR, etc). In C-Kermit 8.0.201 and later, however,
       the "locus" switches to automatically to the remote FTP server
       when you make an FTP connection (see the SET LOCUS description
       [257]Section 7); thus C-Kermit 8.0.201 acts almost exactly like a
       regular FTP client when it has an FTP connection, yet still acts
       like itself on other kinds of connections.
    2. With the REMOTE prefix, it is for a Kermit server (REMOTE CD,
       REMOTE DIR).
    3. With the FTP prefix, it's for an FTP server (FTP CD, FTP DIR).
    4. Also see [258]Section 3.8, which explains "R-commands" and
       "L-commands".

   Kermit's FTP file and directory management commands are as follows.
   When an R-command is included in the Synonyms list, be sure to read
   [259]Section 3.8 about rules for use of R-commands.

   FTP CD [ directory ]
          Tells the FTP server to change its default (working) directory
          to the one given, which usually must be expressed in the syntax
          of the server platform (UNIX, VMS, etc). If the directory is
          not specified, the result depends on the FTP server -- it might
          complain that the command is illegal, or it might change to
          your original login directory. Synonyms: FTP CWD (Change
          Wording Directory); RCD.

   FTP CDUP
          Tells the FTP server to change its default (working) directory
          to the parent directory of its current one (equivalent to
          "cd .." in UNIX, or "cd [-]" in VMS). Synonyms: RCDUP, FTP UP.

   FTP PWD
          Asks the FTP server to report ("print") its current working
          directory. Synonym: RPWD.

   FTP MKDIR directory
          Asks the FTP server to create the directory whose name is
          given. In general, the name must be in the syntax of the
          server's file system, and it must be either absolute (a full
          pathname) or relative to the server's current (working)
          directory. This command fails if the directory can't be created
          for any reason, including that it exists already. Synonym:
          RMKDIR.

   FTP RMDIR directory
          Asks the FTP server to remove the directory whose name is
          given. The rules are the same as for MKDIR, plus in most cases,
          the server will not remove any directory unless it is empty.
          Synonym: RRMDIR.

   FTP DIRECTORY [ filespec ] [ redirectors ]
          Tells the FTP server to send a directory listing of the
          specified files. If no filespec is given, the server lists all
          files in its current working directory. The results are in
          whatever format the server chooses to send them. You can use
          UNIX-like redirectors to send the listing to a file or a
          pipeline, exactly as with the regular Kermit client/server
          REMOTE DIRECTORY command ([260]Using C-Kermit, Chapter 11).
          Synonym: RDIRECTORY. Examples:

    ftp dir                           ; Show listing of all files on screen
    ftp dir *.txt                     ; List *.txt files on screen
    ftp dir *.txt > somefile          ; Put listing in somefile
    ftp dir *.txt >> somefile         ; Append listing to somefile
    ftp dir *.txt | sort > somefile   ; Put sorted listing in somefile
    ftp dir | more                    ; Runs list through "more"
    ftp dir | sort | more             ; Runs list through "sort" and "more"

   FTP VDIRECTORY [ filespec ] [ redirectors ]
          "Verbose" directory. This is an alternative FTP DIRECTORY
          command primarily for use with DECSYSTEM-20 (TOPS-20) FTP
          servers, which send only filenames when given a DIRECTORY
          command; the VDIRECTORY command makes them also send file
          sizes, dates, and attributes.

   FTP CHECK filespec
          Asks the FTP server whether the given file exists or, if the
          filespec contains wildcards, if any files match, and this
          command succeeds or fails accordingly.

   FTP MODTIME filename
          Asks the FTP server, via the not-yet-standard FTP MDTM command,
          to send the modification date and time of the given file. The
          response should be a numeric string in the format:
          yyyymmddhhmmssxxxxx... where yyyy is the year, mm is the month,
          dd is the day, hh is the hour (0-23), mm is the minute, ss is
          the second, and xxx... is the optional fraction of the second
          (0 or more digits). The date and time is expressed in UTC (GMT,
          Zulu, Zero-Meridian). The result is available programmatically
          in the [261]\v(ftp_message) variable, and is understandable by
          Kermit's date-time switches and functions. For example, suppose
          we want to upload all local files that are newer than a
          particular file on the server:

  C-Kermit> ftp modtime signpost
  C-Kermit> echo \v(ftp_message)
  20010807113542.014
  C-Kermit> ftp mput /after:\v(ftp_message)GMT *

          Note that we must append "GMT" to the date-time string to let
          the /AFTER switch know the time is GMT rather than local.

   FTP SIZE filename
          Asks the FTP server to send the size (in bytes) of the given
          file. The result might vary depending on whether the current
          FTP TYPE is binary or text ("ascii"). For a reliable byte
          count, do FTP TYPE BINARY first. The result is available
          programmatically in the [262]\v(ftp_message) variable.

   FTP CHMOD permissions filename
          Tells the FTP server to set the permissions (protection) of the
          given file to the ones given. The permissions and filename must
          be given in whatever syntax is required by the server. Example
          (for a UNIX-based FTP server):

  ftp chmod 664 oofa.txt

          Not all servers support this command. For non-UNIX-based
          servers, you might need to use FTP QUOTE or FTP SITE and the
          appropriate platform-specific FTP server command.

   FTP UMASK [ number ]
          This command is probably specific to UNIX-based servers; it
          sets the UNIX "umask", which is the default permissions mask
          for new (in this case, incoming) files. Crudely put, the UNIX
          umask is an octal representation of a binary number in in which
          a 1 bit stands for a permission bit that must be 0, and a 0 bit
          stands for a permission bit that can be 0 or 1 depending on
          other factors, such as the permissions of the parent directory.
          Example: "umask 007" requires that new files are created
          without read/write/execute world permission. If the number is
          not specified, the server's current umask is reported.

   FTP RENAME filename newname
          Asks the FTP server to rename the file whose name is "filename"
          to "newname". Works only for one file; can not be used with
          wildcards. The server's interpretation of "newname" can vary
          (in some cases it must be a filename, in others perhaps it can
          also be a directory name, in which case if the filename denote
          a regular file, the file might be moved to the given
          directory). Some servers might allow files to be renamed
          ("moved") between physical disks or partitions, others might
          not. Synonym: RRENAME.

   FTP DELETE [ switches ] filespec [ filespec [ ... ] ]
          Tells the FTP server to delete the file or files listed. Each
          file specification may, but need not, contain wildcard
          characters to match multiple files. File specifications and
          wildcard syntax must be those of the server. Any file
          specifications that contain spaces must be enclosed in braces
          or doublequotes. FTP DELETE switches are:

 /ERROR-ACTION:  /FILENAMES:     /NOBACKUPFILES  /QUIET
 /EXCEPT:        /LARGER-THAN:   /NODOTFILES     /NOPAGE
 /PAGE           /RECURSIVE      /SMALLER-THAN:

          When used with FTP DELETE, the /RECURSIVE switch deletes files
          but not directories, and furthermore depends on the server
          providing recursive file lists, which is not the normal
          behavior. For further details, see the decriptions of these
          switches in [263]Section 3.6. Synonyms: FTP MDELETE (Kermit
          makes no distinction between DELETE and MDELETE); RDELETE.

   FTP TYPE { TEXT, BINARY, TENEX }
          Tells the FTP server to change its file-transfer type to the
          one given, immediately. See [264]SET FTP TYPE for details.

   [ [265]Top ] [ [266]FTP Top ] [ [267]C-Kermit Home ] [ [268]Kermit
   Home ]
     _________________________________________________________________

  3.5. Uploading Files With FTP

   Uploading means sending files from the client (Kermit) to the FTP
   server. The basic command for uploading files with FTP is PUT:

   FTP PUT [ switches ] [ filespec [ as-name ] ]
          Uploads (sends) the file or files that match the file
          specification, which may include wildcards, to the server. If
          no filespec is given, the names of files to send are taken from
          the /LISTFILE: file, if any, otherwise from the SEND-LIST, if
          any. Unless you go out of your way to prevent it, Kermit
          determines the transfer mode (text or binary) for each file
          automatically, and switches automatically on a per-file basis.
          If an as-name is given, the file is sent under that name
          instead of its own (if an as-name is given with a wildcard
          filespec, the result is a bit more complicated, and is
          explained later in this section).

   Unlike normal FTP clients, Kermit does not prompt you by default (or
   at all) for each file; it just sends them, just as it does with Kermit
   protocol. The filespec can be a literal filename or a Kermit pattern,
   described in:

  [269]http://www.columbia.edu/kermit/ckermit70.html#x4.9

   Kermit patterns are equivalent to C-Shell patterns and provide a fair
   amount of flexibility in selecting which files to send, which is
   augmented by the file-selection switches presented in [270]Section
   3.5.1.

   FTP MPUT [ switches ] filespec [ filespec [ ... ] ]
          FTP MPUT is just like FTP PUT except it allows you to give more
          than one file specification, and it does not allow an as-name
          in the file list. However, as-names can be given to either PUT
          or MPUT with the /AS-NAME: switch.

   If a PUT or MPUT command results in one file being uploaded, it
   succeeds if the file is uploaded completely and fails otherwise. If
   more than one file is selected for upload, success or failure depends
   on the [271]FTP ERROR-ACTION setting; if it is PROCEED (the default
   setting), then the [M]PUT command succeeds if at least one of the
   files was completely uploaded, and fails otherwise, If FTP
   ERROR-ACTION is QUIT, the [M]PUT command succeeds if all selected
   files were uploaded successfully, and fails if any file failed.

   FTP uploads may be interrupted just like Kermit uploads. While the
   transfer is in progress, type:

  X to interrupt the current file and go on to the next file.
  Z to cancel the current file and all remaining files.
  ^C (Control-C): Like Z, but might act more quickly.

   MPUT may be used as in regular FTP clients, but it is not required to
   send multiple files; in Kermit it is required only if you want to give
   multiple file specifications. Examples:

  ftp put oofa.txt               ; Send a single file oofa.txt
  ftp put oofa.txt budget.txt    ; Send single file oofa.txt as budget.txt
  ftp put *.txt                  ; Send all *.txt files
  ftp mput *.txt                 ; Send all *.txt files (same as "put *.txt")
  ftp mput *.txt foo.bar         ; Send all *.txt files plus foo.bar

   The distinction between PUT and MPUT is important only when more than
   one filespec is given, just like the distinction between Kermit SEND
   and MSEND:

  ftp put oofa.txt budget.txt    ; Send oofa.txt AS budget.txt
  ftp mput oofa.txt budget.txt   ; Send oofa.txt AND budget.txt

   If the source file specification includes any path segments, for
   example:

  put /tmp/oofa.txt
  put subdir/another/andanother/oofa.txt

   the path portion is stripped from the filename that is sent to the
   server. However, if an as-name contains a path, it is retained.
   Examples:

  ftp put /usr/doc/oofa.txt      ; Send as "oofa.txt".
  ftp put oofa.txt /tmp/oofa.txt ; Send as "/tmp/oofa.txt"

   The latter example sends the file oofa.txt from your current local
   directory to the server's /tmp directory. This works only if the
   server uses the same directory notation that you used in the as-name
   AND the given directory already exists on the server AND if you have
   write access to it.

   Use caution when uploading from a case-sensitive file system, such as
   UNIX, to a file system that is not case sensitive, such as Windows or
   VMS. If you have two files in UNIX, AA and aa and upload both of them,
   the second one will overwrite the first. The only way around this
   provided by FTP protocol is its "unique server names" feature (SET FTP
   UNIQUE-SERVER-NAMES or the /UNIQUE switch described below).
     _________________________________________________________________

    3.5.1. FTP PUT Switches

   FTP PUT and MPUT are similar in format and behavior to the regular
   Kermit SEND and MSEND commands, and they allow most of the same
   optional switches:

C-Kermit>ftp put ? Filename, or switch, one of the following:
 /after:                 /larger-than:           /rename-to:
 /array:                 /listfile:              /server-character-set:
 /as-name:               /local-character-set:   /server-rename-to:
 /before:                /move-to:               /simulate
 /binary                 /nobackupfiles          /smaller-than:
 /command                /nodotfiles             /tenex
 /delete                 /nofollowlinks          /text
 /dotfiles               /not-after:             /transparent
 /error-action:          /not-before:            /type:
 /except:                /permissions:           /update
 /filenames:             /quiet                  /unique-server-names
 /filter:                /recover
 /followlinks            /recursive

   Since most of these switches are common to Kermit's SEND and MSEND
   commands, they described only briefly here. For greater detail see:

     [272]http://www.columbia.edu/kermit/ckermit70.html#x1.5 (explanation
   of switches)
     [273]http://www.columbia.edu/kermit/ckermit70.html#x4.7
   (file-transfer switches)

   First the file-selection switches:

   /AFTER:date-time
   /BEFORE:date-time
   /NOT-AFTER:date-time
   /NOT-BEFORE:date-time
          Only send those files modified on or after or before the given
          date and time. These switches can be combined to select files
          modified between two date/times. Various date-time formats are
          accepted; if the date-time contains spaces, it must be enclosed
          in braces or doublequotes. See
          [274]http://www.columbia.edu/kermit/ckermit70.html#x1.6 and
          [275]Section 8.13 of this document for details about date-time
          formats. Examples:

  ftp put /after:{1 jan 2000 0:00:00} *
  ftp put /after:-5days *

   /LARGER-THAN:number
   /SMALLER-THAN:number
          Only send files larger (smaller) than the given number of bytes
          (octets). These switches can be combined to select files in a
          certain size range.

   /TYPE:{TEXT,BINARY}
          Only send files that are the given type, which is determined
          for each file just before sending it by file scanning. BINARY
          includes TENEX; if you have included a /TENEX switch, or
          previously given a [SET] FTP TYPE TENEX command, binary files
          are sent in TENEX, rather than BINARY mode.

   /[NO]DOTFILES
          [Don't] include files whose names begin with dot (.). By
          default, such files are not included unless your filespec
          explicitly mentions them.

   /NOBACKUPFILES
          Don't include files whose names end with .~nnn~, where nnn is a
          number, e.g. oofa.txt.~27~. These are backup files created by
          Kermit, EMACS, and other applications. By default, backup files
          are included.

   /NOFOLLOWLINKS
          (UNIX only) Skip over symbolic links rather than following them
          (default). This applies to wildcard and/or recursive [M]PUTs;
          if a single filename is given, and it happens to be a symbolic
          link, the file it points to is sent.

   /FOLLOWLINKS
          (UNIX only) Always follow (resolve) symbolic links, even in
          wildcard or recursive [M]PUTs. Use with caution. Watch out for
          circular links, endless loops, etc.

   /EXCEPT:pattern
          Exception list -- don't send files whose names match the given
          pattern. See [276]Section 1.5.4 of the [277]C-Kermit 7.0 Update
          Notes for details. If you want to exclude a directory from a
          recursive [M]PUT, use /EXCEPT:{dirname/*}.

   /RECURSIVE
          Sends the desired files from the current (or given) directory,
          plus all directories beneath it, including empty directories,
          replicating the directory structure on the server. No special
          capabilities are required in the server, but of course your
          login ID on the server must have the appropriate access and
          permission to create directories. Recursive PUTs work not only
          between like platforms (e.g. UNIX to UNIX) but also between
          unlike ones (e.g. UNIX to VMS or Windows), in which case
          text-file format differences are handled by Kermit's automatic
          text/binary mode switching ([278]Section 4) and character-set
          translation ([279]Section 3.7). Synonym: /SUBDIRECTORIES.

   /UPDATE
          Send only files that have changed since last time ([280]Section
          3.5.2).

   /ARRAY:arrayname
          The "file" to be sent is an array, or a segment of one, rather
          than a real file. In this case the other selection switches
          don't apply. The array contents are sent in text mode, and each
          array element is treated as a line. Example:

  ftp put /as-name:array.txt /array:&a

          (or, to send a segment of the array, /array:&a[100:199]). If
          you don't include an /AS-NAME, a name of "_array_x_" is used
          (where x is the array letter). If you include this switch, most
          other switches are meaningless and ignored.

   /COMMAND
          The "file" to be sent is the standard output of a command,
          rather than a real file. It is sent in text or binary mode
          according to the prevailing FTP TYPE, which can be overridden
          with a /TEXT or /BINARY switch. Example: Example:

  ftp put /command /as-name:{userlist} {finger | sort -r}

   /LISTFILE:filename
          Tells Kermit to obtain the list of files to be sent from the
          file whose name is given. This file must contain one file
          specification (which may be wild) per line. If the list
          includes files from different directories, such as a recursive
          listing of a directory tree, the paths are recreated on the
          server (if possible) if you include the /RECURSIVE switch;
          otherwise all the files are sent to the current directory on
          the server.

   Now the other switches:

   /AS-NAME:text
          If a single file is being sent, send it with the given text as
          its name. If multiple files are being sent, the text must be a
          template that includes variables such as \v(filename),
          \v(filenumber), \v(ntime), to allow dynamic creation of each
          name. The same applies to the as-name field of the FTP PUT
          command. If this switch is not included (and an as-name is not
          included as the second filename to PUT), each file is sent with
          its own name.

   /BINARY
   /TEXT
   /TENEX
          Forces this upload to take place in the given mode, regardless
          of the current FTP TYPE setting, and without automatic
          text/binary switching. /ASCII is a synonym for /TEXT.

   /FILTER:command
          Specifies that the file(s) is/are to be passed through the
          given command or pipeline on their way to the server. Example:

  ftp put /binary /filter:{gzip -c \v(filename)} /as-name:\v(filename).gz *

   /TRANSPARENT
   /LOCAL-CHARACTER-SET:name
   /SERVER-CHARACTER-SET:name
          Character-set translation for text files, explained in
          [281]Section 3.7.

   /ERROR-ACTION:{PROCEED,QUIT}
          Overrides the prevailing [282]FTP ERROR-ACTION for the duration
          of this PUT or MPUT command only.

   /RECOVER
          Resume an interrupted transfer where from the point of
          interruption (explained in [283]Section 3.5.2). Synonym:
          /RESTART.

   /DELETE
          Tells Kermit to delete each source file immediately after, and
          only if, it has been uploaded completely and successfully.
          This, in effect, moves the file from the client to the server.

   /MOVE-TO:directory
          Tells Kermit to move each source file to the named local
          directory after, and only if, it has been uploaded completely
          and successfully.

   /RENAME-TO:template
          Tells Kermit to rename each (local) source file according to
          the given template after, and only if, it has been uploaded
          completely and successfully. The template works as in /AS-NAME.

   /SERVER-RENAME-TO:template
          Tells Kermit to ask the server to rename each file according to
          the given template as soon as, and only if, it has been
          received completely and successfully. The template works as in
          /AS-NAME. Requires write and rename access on the server, so
          doesn't usually work with (e.g.) anonymous uploads to public
          incoming areas where the permissions don't allow renaming.
          Examples:

        ftp mput /server-rename:\v(filename).ok *
                Appends ".ok" to each filename on the server when it's
                finished uploading.

        ftp mput /as-name:\v(filename).tmp /server-rename:\v(filename) *
                This is the reverse of the previous example; it uses a
                temporary name while uploading is in progress and reverts
                the file to its real name when uploading is complete.

        ftp mput /as-name:\v(filename)
                /server-rename:../final/\v(filename) *
                Moves the file from the working directory to a final
                directory when the upload is complete, but in this case
                you have to know the pathname syntax of the server. If
                the rename fails, the [M]PUT command fails according to
                the [284]FTP ERROR-ACTION selection.

   /FILENAMES:{AUTOMATIC,CONVERTED,LITERAL}
          Overrides the [285]FTP FILENAMES setting for this upload only.

   /PERMISSIONS:{ON,OFF}
          Overrides the [286]FTP PERMISSIONS setting for this upload
          only.

   /UNIQUE
          Tells Kermit to tell the server to give [287]unique names to
          incoming files that would otherwise overwrite existing files
          that have the same name. This switch conflicts with /UPDATE,
          /RECOVER, /PERMISSIONS, and /SERVER-RENAME since the client has
          no way of knowing the name assigned by the server.

   /QUIET
          Don't display file-transfer progress or statistics.

   /SIMULATE
          Shows which files would be sent without actually sending them.
          Useful (for example) with /UPDATE (next section). The results
          are shown in the file-transfer display (if it is not disabled)
          and in the transaction log (if one is active). Hint: use SET
          TRANSFER DISPLAY BRIEF.
     _________________________________________________________________

    3.5.2. Update Mode

   When you include the /UPDATE switch, this means to skip sending any
   file that already exists on the server if the local file's
   modification date/time is not later than that of the corresponding
   file on the server. Here is a typical application for update mode:
   Suppose that on Computer A, you maintain a large set of files (say, a
   collection of Web pages and graphics images, or the source files for a
   software application), and you need to keep a parallel copy on another
   Computer, B. Of course you could upload the entire collection every
   day:

  cd source-directory
  ftp computerb.xyzcorp.com
  ( authentication details... )
  ftp cd target-directory
  ftp put [ switches ] *

   But if the total size is large or the network slow, this would be
   unnecessarily time-consuming. Worse, if other users or sites had to
   update whenever new files appeared in B's directory, this would cause
   them unnecessary work. By including the /UPDATE switch:

  ftp put /update [ other-switches ] *

   only those files that changed since last time are uploaded. Here's how
   it works. For each local file that is selected for uploading:

     * The remote filename is determined in the normal way, according to
       the [288]FTP FILENAMES setting, /FILENAMES switch, or the as-name,
       if any.
     * Kermit sends an MDTM (modification time) command for the
       corresponding remote filename to the server.
     * If the server does not understand the MDTM command, the file is
       sent.
     * If the server can't find a file with the given name, the file is
       sent.
     * If the local file's modification time is later than that of the
       remote file, the file is sent.
     * Otherwise -- the remote file exists but its modification time is
       equal to or earlier than that of the local file -- the file is
       skipped.

   All time comparisons take place in Coordinated Universal Time
   (UTC)([289]1), also known as GMT or Zulu time: Timezone 0; standard
   time, without daylight savings.

     WARNING: Some FTP servers, such as Novell NWFTPD.NLM, ignore or
     misimplement the FTP specification and send local time rather than
     UTC.

   Update mode is useful only when always used in the same direction.
   When you upload (PUT) a file with FTP, the destination file receives
   the current timestamp on the server's computer, not the original
   file's timestamp ([290]2). If you try to FTP PUT /UPDATE the same file
   again, it will be skipped (as expected) since the remote copy is
   newer. However, if you try to FTP GET /UPDATE the same file
   ([291]Section 3.6), it will be transferred for the same reason.

   To check the availability of PUT /UPDATE on a particular connection,
   issue an FTP MODTIME command for a file that is known to exist on the
   server. If it succeeds, PUT /UPDATE should work and in that case, you
   can run a procedure like the one above every day: the first time, it
   sends all the files; after that, it sends only the ones that changed.
   If a transaction log is active, a notation is included for any files
   that are skipped.

   Notes:
    1. Why is Coordinated Universal Time abbreviated UTC? From the
       [292]National Institute of Standards and Technology FAQ: "In 1970
       the Coordinated Universal Time system was devised by an
       international advisory group of technical experts within the
       International Telecommunication Union (ITU). The ITU felt it was
       best to designate a single abbreviation for use in all languages
       in order to minimize confusion. Since unanimous agreement could
       not be achieved on using either the English word order, CUT, or
       the French word order, TUC, the acronym UTC was chosen as a
       compromise."
    2. The Kermit FTP client is unusual in that, when downloading only,
       it can set the received file's date from the file's date on the
       server, but this should not affect the update feature. When
       uploading to an FTP server, however, there is no mechanism for the
       client to set the date of the uploaded file on the server.
     _________________________________________________________________

    3.5.3 Recovery

   Suppose that while you are uploading a large file over a slow
   connection, the connection is lost before the entire file is
   transferred. With most FTP clients, you would have to start over, thus
   resending the portion of the file that was sent already, and that is
   already on the server. But Kermit's /RECOVER switch (Synonym:
   /RESTART) lets you continue an interrupted transfer from the point of
   failure, thus transferring only the part that wasn't sent already. The
   prerequisites for recovery are:

     * The transfer must be in BINARY mode, or else the client and server
       must reside on like systems (e.g. both on some form of UNIX).
     * The FTP server must support the SIZE command.

   Here's how it works. When you include the /RECOVER switch:

     * Kermit checks for conflicting switches, such as /UPDATE and
       /UNIQUE; if /RECOVER is given with these switches an error occurs.
       If /RECOVER is given in other circumstances where it could serve
       no useful purpose (e.g. with arrays, pipes, or filters), it is
       ignored.

   If the switch is accepted, then for each selected file:

     * If it is not binary (determined by scanning) and the client and
       server are not on like platforms, recovery is canceled (the entire
       file is sent). Otherwise:
     * A SIZE command is sent for the file (using its remote name). If
       the reply indicates the file was not found, or the SIZE command
       was not understood, or any other kind of error, recovery is
       canceled. Otherwise:
     * A MDTM (modification time) command is sent for the file. If a
       valid reply is received, and the modification time of the local
       file is later than that of the remote file, recovery is canceled.
       Otherwise:
     * If the sizes of the two files are identical, the file is not sent.
       Otherwise:
     * Kermit seeks to the recovery spot in the local file, tells the
       server to APPEND the data which is about to arrive to the remote
       file, and then sends the data starting at the recovery point.

   To safeguard file integrity, recovery is not attempted unless all the
   preconditions are met. For the widest possible usefulness, APPEND is
   used rather than RESTART. For stream transfers (the only kind that
   Kermit supports) the results are the same.

   By design, the /RECOVER switch can be included with any FTP PUT or
   MPUT command, even if it specifies a group of files. This allows you
   to resume an interrupted batch transfer from where it left off. The
   files that were already completely sent are skipped, the file that was
   interrupted is recovered, and the remaining files are uploaded.

   By the way, it doesn't matter how the original partial file was
   uploaded -- FTP, Kermit, Zmodem, etc: as long as the preconditions are
   met, it can be recovered with FTP PUT /RECOVER, or for that matter
   also using Kermit protocol and SEND /RECOVER.

   A word of caution, however, when the original upload was in text mode
   with character-set translation ([293]Section 3.7):

     * If the original upload involved a translation from one single-byte
       character set to another (e.g. Code Page 850 to Latin-1), recovery
       is safe if you specify the same translations for the recovery. If
       you don't, the resulting file will contain a mixture of character
       sets.
     * If the original upload involved a translation that changed the
       size of the file (e.g. from an alphabetic Code Page or Latin
       Alphabet to Unicode, or vice versa), recovery is NOT safe, even if
       you specify the same translations.

   Kermit has no way of knowing anything about the previous upload. As a
   safeguard, an error occurs if you include /RECOVER and also specify a
   character-set of UCS2 or UTF8, since recovery can't possibly work in
   that situation. Otherwise, it's up to you to avoid unsafe recovery
   operations.

   [ [294]Top ] [ [295]FTP Top ] [ [296]C-Kermit Home ] [ [297]Kermit
   Home ]
     _________________________________________________________________

  3.6. Downloading Files With FTP

   Although uploading files with Kermit's FTP client is just as easy and
   flexible as sending files with Kermit protocol, the same is not always
   true for downloading because FTP servers lack some of the capabilities
   of a Kermit server:

     * If you want to get more than one file, you have to use MGET, not
       GET, since the underlying FTP protocol is different in the two
       cases. Kermit can't "autodetect" which one you mean, as it can
       with PUT and MPUT, since it can't be expected to know the wildcard
       syntax of the remote platform and/or FTP server (the same is true
       for all other FTP clients). To complicate matters, FTP protocol
       now includes two underlying mechanisms (NLST and MLSD) for
       accomplishing MGET operations and, as explained in [298]Section
       3.11, the two behave differently.
     * Automatic text-binary mode switching is not done by the server. It
       can be done by the client (Kermit), but in this case it is not
       based on a file scan (since there is no way for Kermit prescan a
       server file), but rather on the filename, using C-Kermit 7.0
       [299]filename patterns.
     * Some options that are available with FTP PUT can not be used with
       FTP [M]GET or don't work the same way:
         /PERMISSIONS (FTP protocol has no mechanism for this).
         /[NOT-]BEFORE, /[NOT-]AFTER (because of the timezone problem).
         /RECOVER works only in binary mode.   /RECURSIVE has limited
       utility.

   The commands for downloading are:

   SET FILE DOWNLOAD-DIRECTORY [ directory ]
          As with Kermit transfers, this command, if given, tells
          C-Kermit where to store incoming files in the absence of a
          specific as-name. If not given, incoming files are stored as
          indicated by the as-name, if any, otherwise in the current
          directory, just as with Kermit transfers. The more verbose
          transfer display formats give the full pathname of each
          received file, and, in case you have trouble finding a
          downloaded file afterwards, its full path is also listed in the
          transaction log (if you kept one), and you can also ask Kermit
          where it went with the [300]WHERE command.

   SET FTP GET-FILETYPE-SWITCHING { ON, OFF }
          ON by default, causing Kermit to switch automatically into text
          or binary mode for each file based on whether its name matches
          a text pattern or binary pattern. Set this OFF, or use a /TEXT,
          /BINARY, or /TENEX switch to defeat this feature. Use SHOW
          PATTERNS to see the current pattern list.

   [ FTP ] GET [ switches ] filename [ as-name ]
          Asks the server to send the given file, and if it comes, stores
          it locally under the given as-name, if any, otherwise under its
          original name (modified according to the selected filename
          conversion option), in your download directory, if you have
          specified one, otherwise in the directory indicated in the
          as-name, if any, otherwise in your current directory. If you
          accidentally use a wildcard in the filename ("get *.txt") the
          server will reply with a message like "File not found" (unless
          there is a file whose name actually is "*.txt"). If FTP
          GET-FILETYPE-SWITCHING is ON, and in the absence of any GET
          switches to override it, the file is transferred in binary mode
          if it matches any of Kermit's binary name patterns, and in text
          mode if it matches any of Kermit's text name patterns, and in
          the prevailing FTP TYPE if it matches none of these patterns.

   [ FTP ] MGET [ switches ] filespec [ filespec [ filespec [ ... ] ] ]
          Like GET, but for multiple files. One or more file
          specifications can be given, and any or all (or none) of them
          can contain wildcards or can be directory names. The file list
          may not include an as-name, but you can still give one with the
          /AS-NAME: switch.

   In both the FTP GET and MGET commands, any filenames that contain
   spaces must be enclosed in braces or doublequotes (see [301]Section 5
   for details).

   FTP downloads may be interrupted just like Kermit transfers. While the
   transfer is in progress, type:

     * X to interrupt the current file and go on to the next file.
     * Z (or Control-C) to cancel the current file and all remaining
       files.

   Before proceeding, a brief word about temporary files. In FTP
   protocol, the MGET command works by requesting a file list from the
   server, and then (internally) issuing a GET command (FTP RETR protocol
   directive) for each file. The file list returned by the server can be
   any size at all, so in case it is huge, we don't store it in memory;
   instead we put it in a temporary file. For troubleshooting purposes,
   you should be aware of two points:

    1. The location of the temporary file is chosen according the TMP or
       TEMP environment variables. If neither of these variables is
       defined, you might need to define it. In case there is not enough
       space on the indicated disk or partition for the server's file
       list, you might need to either clean up the temporary area, or
       redefine the environment variable to indicate a different area
       that has sufficient space.
    2. If you want to look at the list yourself, use SET FTP DEBUG ON.
       This tells Kermit to (a) give you the full pathname of the
       temporary file at the end of each MGET command, and (b) not to
       delete it, as it normally does.
     _________________________________________________________________

    3.6.1. FTP GET Switches

   The following switches are available with FTP GET and MGET:

   /TEXT
          Specifies a text-mode transfer. Overrides the global FTP TYPE
          setting and filename pattern-matching for the duration of the
          current command only, All files are downloaded in text mode.
          Synonym: /ASCII.

   /BINARY
          Specifies a binary-mode transfer. Overrides the global FTP TYPE
          setting and filename pattern-matching for the duration of the
          current command only. All files are downloaded in binary mode.

   /TENEX
          Like /BINARY but specifies a special binary transfer mode to be
          used when getting 8-bit binary files from a 36-bit platform
          such as TOPS-10, TOPS-20, or TENEX. All files are downloaded in
          the special binary mode.

   /RECOVER
          This instructs Kermit to try to recover an incomplete download
          from the point of failure. Works only in binary mode, and only
          if the server supports the (not-yet-standard) FTP "REST"
          directive. See [302]Section 3.6.3 for details. Synonym:
          /RESTART.

   /FILENAMES:{CONVERTED,LITERAL}
          Overrides the [303]FTP FILENAMES (filename conversion) setting
          for this download only, forcing incoming filenames to be either
          converted or taken literally.

   /AS-NAME:text
          For GET, this is equivalent to giving an as-name after the
          filename. For MGET, this is the only way to specify alternative
          names for the incoming files. With MGET, the /AS-NAME text
          should (must) contain a Kermit variable, usually \v(filename)
          or \v(filenumber). Example:

  mget /text /as-name:\v(filename).new *.c

          This gets all ".c" files and stores them with "

          .new" appended to their names. See the [304]C-Kermit 7.0 Update
          Notes for details.

   /COMMAND
          This specifies that the incoming file is to be written to the
          standard input of a command, rather than to a file. The command
          name is the as-name from the GET command or the /AS-NAME
          argument. If you need to refer to the incoming file's name in
          the command, use \v(filename). See the description of the
          regular Kermit [305]GET /COMMAND command for details and
          examples.

   /QUIET
          Transfers the files quietly; don't put up a file-transfer
          display.

   /ERROR-ACTION:{QUIT,PROCEED}
          This switch affects only MGET. If an error occurs with a
          particular file, this tells whether to go on to the next file
          (PROCEED) or to stop right away and fail (QUIT). The default is
          PROCEED.

   The file selection switches are:

   /EXCEPT:{pattern} or /EXCEPT:{{pattern}{pattern}{...}}
          Exception list for MGET; skip downloading any file whose name
          matches any of the given patterns (when using the second
          format, up to 64 patterns may be specified). [306]CLICK HERE
          for syntax details.

   /SMALLER-THAN:number
          Download only files whose size is smaller than the given number
          of bytes (octets). Requires that the FTP server support the
          SIZE or MLSD directive.

   /LARGER-THAN:number
          Download only files whose size is greater than the given number
          of bytes. Requires that the FTP server support the SIZE or MLSD
          directive.

   /NOBACKUPFILES
          During MGET, don't download any files whose names end with
          backup suffixes (.~n~ where n is a number).

   /NODOTFILES
          During MGET, don't download any files whose names begin with
          period (.). Equivalent to /EXCEPT:{.*}.

   /LISTFILE:local-filename
          The given file contains a list of files to GET, one per line.
          Filenames in the listfile can contain wildcard characters in
          the syntax of the server. There is no limit on the number of
          lines in the listfile.

   /NAMELIST:local-filename
          If this switch is given, then instead of actually retrieving
          the selected files, the GET command retrieves a list of the
          names of the files that would be retrieved, and places it in
          the specified file. The resulting file is an ordinary text file,
          with one filename per line, suitable for reading by a person,
          or processing by a computer program, including Kermit itself
          (FOPEN / FREAD / FWRITE / FCLOSE), and as /FILELIST: file. If
          the filename is omitted or given as "-" (dash, hyphen), the
          list goes to the screen. NOTE: if you want a copy of the
          complete list sent by the server, use SET FTP DEBUG ON, perform
          an MGET, and the temporary file containing the list will be
          kept rather than deleted (and Kermit tells you its name).

   /UPDATE, /COLLISION:keyword
          Explained in [307]Section 3.6.2.

   /RECURSIVE
          This means to try to download an entire directory tree, rather
          than just files from a particular directory. In fact, FTP
          protocol does not provide a method to request a recursive
          download (unless the server supports MLSD; see [308]Section
          3.11), so this works only if the FTP server does it anyway,
          without being asked, as some do. In this case, Kermit detects
          that names in the returned file list contain directory
          separators, and therefore attempts to create the needed
          directories as the files arrive. But this can work only if the
          server is on the same kind of platform as the client, so the
          pathname syntax can be recognized, and also because the server
          does not switch between text and binary mode, which would be
          vital for cross-platform transfers. Use with caution. Synonym:
          /SUBDIRECTORIES.

          Even when the server does not provide recursive file lists,
          [M]GET /RECURSIVE forces Kermit to replicate any directory
          structure implied or expressed by the server's file list. For
          example:

  get somepath/somefile

          Gets the file named somefile from the server's somepath
          directory and puts it Kermit's current (or download) directory,
          whereas:

  get /recursive somepath/somefile

          creates the path locally and then puts the file in it.
          Similarly for MGET:

  mget */data/*

          downloads all the files in all the data subdirectories of all
          the subdirectories of the server's current directory and stores
          them locally in Kermit's current (or download) directory,
          whereas:

  mget /recursive */data/*

          re-creates the server's directory structure locally.

   The FTP protocol does not include explicit mechanisms for recursion,
   so Kermit builds upon what is available. Although an Internet draft
   describes a mechanism ("MLSD") that would allow protocol-driven
   recursion, similar to Kermit's File Attribute packets (circa 1984), it
   has not yet attained RFC or standard status, and servers are not yet
   widely available that offer this feature. In the meantime, the
   effectiveness of MGET /RECURSIVE depends on the FTP server
   implementation. If the server returns a recursive list in response to
   the standard NLST command (whose behavior is ill-defined), Kermit's
   FTP MGET /RECURSIVE command uses it to re-create the remote directory
   tree locally. If the server supports MLSD, C-Kermit 8.0.206 and Kermit
   95 2.1 and later are able to sense it automatically and use it, as
   described below in [309]Section 3.11.

   The /BEFORE:, /AFTER:, /NOT-BEFORE:, and /NOT-AFTER: switches are not
   available for downloading because of the confusion with timezones.
   Would the given times be in the local timezone, the server's timezone,
   or GMT? The FTP server's directory listings show its own local times
   but since we don't know what timezone the server is in, there's no way
   to reconcile our local times with the server's. Similarly,
   /PERMISSIONS can't be preserved in downloads because FTP protocol
   provides no means of querying the server for a file's permission.

   Source-file disposition switches:

   /DELETE
          Each file that is downloaded successfully is to be deleted from
          the server. Requires the appropriate file access rights on the
          server.

   /SERVER-RENAME-TO:template
          Asks the server to rename each (remote) source file immediately
          after, and only if, it is sent correctly. See [310]PUT
          /SERVER-RENAME-TO: for details.

   Destination-file disposition switches:

   /TO-SCREEN
          Displays the incoming file on the screen rather than storing it
          on disk. If this switch is given, the /RENAME-TO and /MOVE-TO
          switches are ignored, the file-transfer display is suppressed,
          and the given file(s) is/are shown on the screen. Can be used
          with /FILTER, e.g.

  get /text /to-screen /filter:more oofa.txt

          In fact, you should always use /TO-SCREEN with /FILTER or
          /COMMAND when the command would result in displaying the
          incoming file on the screen; otherwise C-Kermit would have no
          way of knowing to suppress its file transfer display (since it
          can't be expected to know what the command or filter does).

   /RENAME-TO:template
          Each file that is downloaded is to be renamed as indicated if
          and only if it was received completely and without error. The
          template can be literal text or can contain variables that are
          evaluated for each file. For MGET, the text must contain
          variables; for GET it can be a literal string. The \v(filename)
          variable contains the name of the current file, so:

  ftp mget /rename-to:\v(filename).ok *

          causes each file that is successfully downloaded to have ".ok"
          appended to its name. For details see [311]Section 4.1 of the
          [312]C-Kermit 7.0 Update Notes.

   /MOVE-TO:text
          Just like /RENAME-TO:, except the text denotes the name of a
          directory to which successfully downloaded files are to be
          moved. If the directory does not exist, it is created.

   The file transfer display does not show the /MOVE-TO or /RENAME-TO
   value, since the incoming file has not yet been moved or renamed.
     _________________________________________________________________

    3.6.2. Filename Collisions

   What should happen if an incoming file has the same name as an
   existing file in the same directory? By default, Kermit's FILE
   COLLISION setting applies: BACKUP, RENAME, UPDATE, DISCARD, etc, as
   described in [313]Using C-Kermit. Kermit's default FILE COLLISION
   setting is BACKUP (rename the existing file and store the incoming
   file under its own name) and therefore this is also the default FTP
   collision action.

   The name under which an incoming file is to be stored is determined as
   follows:

     * If an as-name was given, the as-name is used. Otherwise:
     * If the client and server platforms are alike or [314]FTP FILENAMES
       is set to LITERAL (or the /FILENAMES:LITERAL switch was given for
       this download), the incoming filename is used literally.
       Otherwise:
     * The incoming filename is converted to a form that is friendly to
       the local platform. For UNIX, for example, incoming filenames that
       are all uppercase (as they might be from, say, VMS or an IBM
       mainframe) are converted to lowercase.

   If the resulting name coincides with the name of a local file that
   already exists, we have a filename collision. Collisions are handled
   according to the currently selected collision action:

   SET FTP COLLISION { BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE
          }
          This establishes a filename collision for FTP, separate from
          the Kermit one. The initial FTP collision setting is inherited
          from Kermit's FILE COLLISION setting when the first FTP command
          is given, but subsequent changes to Kermit's FILE COLLISION
          setting do not affect the FTP COLLISION setting. SHOW FTP tells
          the current FTP COLLISION setting.

   FTP GET /COLLISION:{BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE}
          Overrides the current FTP COLLISION action for this download
          only.

   FTP GET /UPDATE
          This is equivalent to GET /COLLISION:UPDATE, and is included
          for symmetry with PUT /UPDATE

   FTP GET /UPDATE and /COLLISION:UPDATE mean to download only those
   files whose modification dates on the server are later than those on
   the client. Date-time comparisons are done in Coordinated Universal
   Time (UTC, GMT, ZULU). The command:

     FTP MGET /COLLISION:APPEND /AS-NAME:newfilename *.*

   Downloads all matching remote files into a single local file (in
   whatever order the server sends them).
     _________________________________________________________________

    3.6.3. Recovery

   Recovery is available for downloads too, but there are some
   differences from the uploading case described in [315]Section 3.5.3:

     * The transfer must be in BINARY mode. It can not be in text mode,
       even if the FTP server is on the same kind of platform as Kermit,
       and even if there is no character-set translation. The original
       download must also have been in binary mode.
     * The FTP server must support the REST ("restart") directive.
       Unfortunately, this is not a standard command; at this writing, it
       is described only in an Internet Draft, not an RFC or Internet
       Standard, but nevertheless it is found in several popular FTP
       servers, such as [316]ProFTPD.

   Here's how download recovery works:

     * Kermit checks for conflicting switches, such as /UPDATE, /COMMAND,
       or /FILTER. If /RECOVER is given with these switches an error
       occurs.
     * The prevailing transfer mode (SET FTP TYPE) must be BINARY. If it
       is not, the /BINARY switch must have been included with the FTP
       [M]GET command.

   If the /RECOVER switch is accepted, then for each selected file:

     * A SIZE command is sent for the file (using its remote name). If
       the reply indicates the file was not found, or the SIZE command
       was not understood, or any other kind of error, recovery is
       canceled (i.e. the entire file is downloaded).
     * If the sizes of the two files are identical, the file is not sent.
       Otherwise:
     * Kermit sends the REST directive to the server, indicating the size
       of the local file. If the server responds affirmatively, Kermit
       opens the local file in append mode and appends the incoming data
       to it. Otherwise, recovery is canceled and the entire file is
       downloaded.

   The /RECOVER switch can be included with any FTP GET or MGET command,
   even if it specifies a group of files. This lets you resume an
   interrupted batch transfer from where it left off. The files that were
   already completely sent are skipped, the file that was interrupted is
   recovered, and the remaining files are uploaded. BUT... unlike with
   uploading, where this can be done with any mixture of text and binary
   files, when downloading, it can only be done if all the files are
   binary.

   It doesn't matter how the original partial file was downloaded -- FTP,
   Kermit, HTTP, Zmodem, etc: as long as the preconditions are met, it
   can be recovered with FTP [M]GET /RECOVER, or for that matter also
   with GET /RECOVER (using Kermit protocol).

   [ [317]Top ] [ [318]FTP Top ] [ [319]C-Kermit Home ] [ [320]Kermit
   Home ]
     _________________________________________________________________

  3.7. Translating Character Sets

   A possibly unique feature of Kermit's FTP client is its ability to
   convert character sets when transferring files in text mode,
   independent of the capabilites of the FTP server, as well as to
   translate the character sets of filenames regardless of transfer mode.
   For compatibility with existing FTP clients, and because there is a
   certain performance penalty, Kermit won't do this unless you ask for
   it. If you enable this feature, you need to inform Kermit of the
   character set (to be) used on the server and in some cases (explained
   below) also the local file character set. This discussion assumes you
   know a bit about character sets (as you must if you have to use them);
   see Chapter 16 of [321]Using C-Kermit for a detailed treatment. The
   Kermit commands for FTP character-set conversion are:

   SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
          Whether to translate character sets when transferring text
          files with FTP. OFF by default. Set this to ON to enable
          character-set translation for subsequent FTP uploads and
          downloads.

   SET FTP SERVER-CHARACTER-SET [322]name
          Text character set (to be) used by the server. Most FTP servers
          are ignorant of character sets, so all translations are done
          unilaterally by Kermit's FTP client. This means that when
          downloading files, you must know in advance the character-set
          used in the files you are downloading (and in their names).
          When uploading, you must specify the character-set to which
          local filenames and text-file contents are to be translated for
          transmission to the server. If you SET FTP
          CHARACTER-SET-TRANSLATION ON but do not specify an FTP
          SERVER-CHARACTER-SET, [323]UTF8 is used, since this is the new
          Internet standard international character set; it is upwards
          compatible with ASCII and it encompasses most written languages
          and therefore does not favor any particular group of people, as
          any other default would do. If you SET FTP SERVER-CHARACTER-SET
          to something (anything) when FTP CHARACTER-SET TRANSLATION is
          OFF, this also sets the latter ON.

   SET FILE CHARACTER-SET [324]name
          This is the regular Kermit (non-FTP-specific) command for
          identifying the character set (to be) used in local text files
          and filenames.

   TO REITERATE: If you SET FTP CHARACTER-SET TRANSLATION ON but do not
   specify an FTP SERVER-CHARACTER-SET, outbound text files are converted
   to UTF-8 and inbound text files are assumed to be UTF-8. If this is
   not appropriate, be sure to also specify the desired FTP
   SERVER-CHARACTER-SET.

   You can use "special" (non-ASCII) characters in filenames in all the
   client / server file management commands (FTP MKDIR, RMDIR, DIRECTORY,
   VDIRECTORY, DELETE, etc), and also in file-transfer commands. When
   giving commands such as FTP DIR (RDIR) and FTP PWD (RPWD), the reply
   is translated too, so you can read it. In this example, the client and
   server use entirely different codes to represent the special
   characters of German:

  C-Kermit> ftp xyzcorp.de /anonymous
  C-Kermit> set ftp server-character-set latin1
  C-Kermit> set file character-set german
  C-Kermit> rcd Stdte
  C-Kermit> rpwd
  "/pub/ftp/Stdte is current directory"
  C-Kermit> rdir
  -rw-rw----  1 olaf     54018 Jan  6 17:58 Adenbttel.txt
  -rw-rw----  1 ursula     373 Jan  5 15:19 Alar.txt
  -rw-rw----  1 gisbert    482 Jan  5 15:20 Blowatz.txt
  -rw-rw----  1 gudrun     124 Jan  5 15:19 Bblingen.txt
  -rw-rw----  1 olga     14348 Jan  7 14:23 Kln.txt

   When the client and server file systems use different character sets,
   you should take care to use only those characters that the two sets
   share in common when creating filenames or text-file contents. For
   example, PC code pages contain a lot line- and box-drawing characters,
   and sometimes "smart quotes", etc, that are not found in ISO standard
   8-bit character sets. You should be especially careful to avoid using
   such characters in filenames.

   [ [325]C-Kermit Character Sets ]
     _________________________________________________________________

    3.7.1. Character Sets and Uploading

   Kermit's PUT and MPUT commands include full file-scanning
   capabilities, as described in [326]Section 4. Thus if FTP
   CHARACTER-SET-TRANSLATION is ON and your character-set associations
   are set up appropriately, Kermit automatically switches on a per-file
   basis between text and binary mode, and for each text file between
   your chosen 7-bit text character set (e.g. ASCII or ISO 646 German),
   8-bit text (e.g. Latin-1 or Japanese EUC), UCS-2, and UTF-8, and
   converts each of these automatically to the server character-set, and
   furthermore automatically differentiates between the Little and Big
   Endian forms of UCS-2, always sending in Big Endian form.

     WARNING: It is not advisable to use UCS-2 (or any Unicode
     transformation other than UTF-8) "on the wire", i.e. as a server
     character set. Most FTP servers are not able to cope with it, since
     it contains lots of 0 (NUL) characters. If you do use it, Kermit
     does not translate filenames to or from UCS-2, for reasons well
     known to C programmers (for example, UNIX APIs assume filename
     strings are NUL-terminated). [327]UTF-8 is the preferred (and
     standard) Unicode format for the Internet.

   FTP character-set translations differ from the regular Kermit ones by
   not restricting translations to a file-character-set /
   transfer-character-set pair. You can have Kermit's FTP client
   translate between any pair of character sets it knows about. You can
   see the list of supported character sets by typing either of the
   following:

  set ftp server-character-set ?
  set file character-set ?

   A typical list looks like this ([328]CLICK HERE for an explanation of
   the names):

  C-Kermit>set file char ? One of the following:
   ascii            cp869-greek       hebrew-7         mazovia-pc
   british          cyrillic-iso      hebrew-iso       next-multinational
   bulgaria-pc      danish            hp-roman8        norwegian
   canadian-french  dec-kanji         hungarian        portuguese
   cp1250           dec-multinational iso2022jp-kanji  shift-jis-kanji
   cp1251-cyrillic  dg-international  italian          short-koi
   cp1252           dutch             jis7-kanji       spanish
   cp437            elot927-greek     koi8             swedish
   cp850            elot928-greek     koi8r            swiss
   cp852            euc-jp            koi8u            ucs2
   cp855-cyrillic   finnish           latin1-iso       utf8
   cp858            french            latin2-iso
   cp862-hebrew     german            latin9-iso
   cp866-cyrillic   greek-iso         macintosh-latin
  C-Kermit>

   Thus you can translate not only between private sets (like PC code
   pages) and standard ones (like Latin-1) as in Kermit protocol, but
   also between any given pair of private sets (e.g. CP852 and Mazovia).
   All conversions go through Unicode as the intermediate character set,
   resulting in a minimum of character loss, since Unicode is a superset
   of all other character sets known to Kermit.

   In addition to the SET commands listed above, the FTP PUT and MPUT
   commands include switches that apply only to the current command:

   /LOCAL-CHARACTER-SET:name
   /SERVER-CHARACTER-SET:name
          Use these switches to force a particular translation. These
          switches override the global FTP CHARACTER-SET-TRANSLATION and
          SERVER-CHARACTER-SET settings and also character-set
          differentiation by file scanning for the duration of the PUT or
          MPUT command. The file scan is still performed, however, to
          determine whether the file is text or binary; thus these
          switches do not affect binary files unless you also include the
          /TEXT switch to force all files to be treated as text.

   In other words, if you include one or both of these switches with a
   PUT or MPUT command, they are used. Similarly, the /TRANSPARENT switch
   disables character-set translation for the PUT or MPUT command despite
   the prevailing FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET
   settings.

   When uploading, the FILE CHARACTER-SET setting is ignored unless you
   have forced Kermit not to [329]scan local files by including a /TEXT
   or /BINARY switch with your [M]PUT command, or by disabling automatic
   text/binary switching in some other way.

   Examples:

    1. Suppose you have a CP852 (East European) text file that you want
       to upload and store in ISO Latin Alphabet 2 encoding:
  ftp put /local-char:cp852 /server-char:latin2 magyar.txt
    2. Suppose you always want your text files converted to Latin-2 when
       uploading with FTP. Then put:
  set ftp server-character-set latin2
       in your Kermit customization file, and then you can omit the
       /SERVER-CHARACTER-SET: switch from your FTP PUT commands:
  ftp put /local-char:cp852 magyar.txt
    3. Now suppose that all the text files on your PC are written in
       Hungarian, but they have a variety of encodings, and you don't
       want to have to include the /LOCAL-CHARACTER-SET: switch on every
       FTP PUT command, or (more to the point) you want to be able to
       send a mixture of these files all at once. Put these commands in
       your Kermit customization file:
  set ftp server-character-set latin2            ; ISO 8859-2
  set file default 7-bit-character-set hungarian ; ISO 646 Hungarian
  set file default 8-bit-character-set cp852     ; PC East European Code Page
       and now PUT and MPUT will automatically detect and switch among
       ISO 646 Hungarian, Code Page 852, UTF-8, and UCS-2 encodings,
       translating each one to Latin-2 for uploading:
  ftp put *.txt

   And since binary files are also detected automatically, the latter can
   be simplified to:

  ftp put *

   even when "*" matches a diverse collection of binary and text files,
   because translations are skipped automatically for binary files.
     _________________________________________________________________

    3.7.2. Character Sets and Downloading

   The commands and switches are the same as for uploading, but automatic
   character-set switching works differently, since Kermit can't scan the
   server files in advance. Instead, the transfer mode (text or binary)
   is based on the filenames; each name is compared with Kermit's list of
   text name patterns and binary name patterns. If the name matches a
   binary pattern (for example, if the filename is oofa.tar.gz and one of
   the filename patterns is "*.gz"), the file is downloaded in binary
   mode; otherwise if it matches a text pattern (e.g. oofa.txt matches
   "*.txt"), it is transferred in text ("ascii") mode. Otherwise, it is
   transferred in the prevailing FTP TYPE.

   In C-Kermit 8.0, the pattern lists used with FTP GET are not the same
   lists used with Kermit transfers, and can not be viewed with SHOW
   PATTERNS, nor adjusted with ADD and REMOVE TEXT-PATTERNS and
   BINARY-PATTERNS, or SET FILE TEXT-PATTERNS and BINARY-PATTERNS.
   Configuration of the FTP patterns list will be added in a future
   release.

   Examples:

   get /server-char:latin1 /local-char:cp850 Gre.txt
          In this command, the filename contains special characters,
          which you enter using whatever character set your local
          computer uses, in this case PC Code Page 850 (cp850). The
          command tells Kermit (in case it didn't know already from its
          FILE CHARACTER-SET setting) that the local character set is
          cp850 and the server's character-set is ISO 8859-1 Latin
          Alphabet 1 (latin1). Kermit translates the filename from cp850
          to latin1 and sends the latin1 name to the server. Since it's a
          text file (matches "*.txt"), its contents are translated to
          cp850 on arrival, and it is saved with a cp850 name.

   mget /text /server:latin1 /local:utf8 *.txt
          This command:

          + Tells C-Kermit that the server's files are encoded in ISO
            8859-1 Latin Alphabet 1.
          + Tells C-Kermit to translate the incoming files into Unicode
            UTF-8 for storage.
          + Asks the server to send all ".txt" files in text mode.

   mget /server:latin1 /local:utf8 *
          Tells Kermit to get all files from the server's directory,
          switching between text and binary mode based on the filename.
          The names of all the files are translated (to UTF-8 in this
          case), but contents are translated (also to UTF-8) only for
          text files.

   Note that any pair of 8-bit character sets is likely to have some
   incompatibilities. Any characters in the source file that do not have
   equivalents in the destination file's character set are converted to
   question marks. This applies to both filenames and to text file
   contents.

   Also note that the server's ability to accept special characters in
   filenames depends on the particular server. For example:

  get Gre.txt

   works with WU-FTPD, but:

  mget Gr*.txt

   does not.
     _________________________________________________________________

    3.7.3. RFC2640

   [330]RFC2640, July 1999, specifies a method by which the FTP client
   and server can negotiate the use of UTF8. However, RFC2640-capable
   servers are rare to nonexistent at this writing, and in any case you
   don't need them to be able to transfer text in UTF8. C-Kermit lets you
   upload and download text files in any character set it knows about,
   converting to or from any other character set it knows about, without
   the knowledge, permission, or cooperation of the server, and
   regardless of its capabilities.

   [ [331]Top ] [ [332]FTP Top ] [ [333]C-Kermit Home ] [ [334]Kermit
   Home ]
     _________________________________________________________________

  3.8. FTP Command Shortcuts

   C-Kermit's FTP client coexists with other C-Kermit functions by
   requiring the "ftp" prefix for each FTP-related command: FTP OPEN, FTP
   GET, FTP BYE, and so on. For interactive use, however, this can be
   rather awkward and sometimes surprising, for example when a GET
   command starts a Kermit GET rather than an FTP GET. In fact, many
   Kermit commands might just as easily apply to an FTP connection: GET,
   PUT (SEND), BYE, and CLOSE. The following command lets you choose how
   these commands are interpreted:

   SET GET-PUT-REMOTE { AUTO, KERMIT, FTP }
          Controls the orientation of GET, PUT, REMOTE and other
          file-transfer and client/server commands that might apply to
          either Kermit or FTP. The default setting is AUTO, meaning that
          these commands apply to FTP if an FTP connection is open, and
          to Kermit otherwise. KERMIT means they always apply to Kermit,
          FTP means they always apply to FTP.

   Here is a complete list of affected commands:

 Kermit Command               FTP Equivalent
  (none)                       FTP [ OPEN ]
  LOGIN                        FTP USER
  LOGOUT                       FTP RESET
  BYE                          FTP BYE
  FINISH                       FTP BYE
  CLOSE                        FTP BYE
  HANGUP                       FTP BYE
  BINARY                       FTP TYPE BINARY
  TEXT (or ASCII)              FTP TYPE ASCII
  SEND (or PUT)                FTP PUT
  MSEND (or MPUT)              FTP MPUT
  RESEND                       FTP PUT /RECOVER
  CSEND                        FTP PUT /COMMAND
  GET                          FTP GET
  MGET                         FTP MGET
  REGET                        FTP GET /RECOVER
  REMOTE HELP      (RHELP)     FTP HELP
  REMOTE CD        (RCD)       FTP CD (CWD)
  REMOTE PWD       (RPWD)      FTP PWD
  REMOTE DIRECTORY (RDIR)      FTP DIRECTORY
  REMOTE DELETE    (RDEL)      FTP DELETE
  REMOTE MKDIR     (RMKDIR)    FTP MKDIR
  REMOTE RMDIR     (RRMDIR)    FTP RMDIR
  REMOTE RENAME    (RRENAME)   FTP RENAME
  REMOTE TYPE      (RTYPE)     FTP TYPE
  REMOTE EXIT      (REXIT)     FTP BYE

   The commands in the right-hand column always access FTP. The commands
   in the left column can access either Kermit protocol or FTP:

     * When GET-PUT-REMOTE is set to KERMIT, or to AUTO when there is no
       FTP connection, the commands in the left-hand column access Kermit
       protocol, and those right-hand column are required for FTP.
     * When GET-PUT-REMOTE is set to FTP, or to AUTO when there is an
       active FTP connection, the commands in the left-hand column access
       the FTP connection and can not be used to access Kermit protocol.
       In this case, if you want to be able to use both Kermit protocol
       and the FTP connection, you must SET GET-PUT-REMOTE KERMIT, and
       then use the FTP commands in the right-hand column to access the
       FTP connection.

   Note that file-management commands such as DIRECTORY, DELETE, CD, PWD,
   MKDIR, RMDIR, HELP, RENAME, COPY, TYPE, and so on, always apply
   locally, no matter what kind of connection you have. This is the
   opposite of most FTP clients, where these commands are intended for
   the server, and require an "L" prefix for local execution (e.g. "dir"
   gets a directory listing from the server, "ldir" gets a local
   directory listing). To illustrate with the CD command and a typical
   UNIX FTP client:

 Client   Server      Change Local Directory     Change Remote Directory
  FTP      FTP         lcd                        cd (cwd)
  Kermit   Kermit      cd                         rcd, remote cd
  Kermit   FTP         cd                         ftp cd, rcd, remote cd

   Also note that not all REMOTE commands are useful with FTP, since FTP
   servers do not offer the corresponding functions. These include:

     * REMOTE ASSIGN  - FTP servers don't have variables
     * REMOTE COPY    - FTP servers don't copy files
     * REMOTE HOST    - FTP servers don't execute host (shell) commands
     * REMOTE KERMIT  - FTP servers don't execute Kermit commands
     * REMOTE PRINT   - FTP servers don't print files
     * REMOTE QUERY   - FTP servers don't have variables
     * REMOTE SET     - FTP servers don't have Kermit settings
     * REMOTE WHO     - FTP servers don't send user lists

   Finally note that command shortcuts do not apply to the HELP command.
   For help about an FTP command, use (for example) "help ftp delete",
   not "help delete" or "help rdelete".

   [ [335]Top ] [ [336]FTP Top ] [ [337]C-Kermit Home ] [ [338]Kermit
   Home ]
     _________________________________________________________________

  3.9. Dual Sessions

   You can have an FTP session open at the same time as a regular Kermit
   SET LINE or SET HOST (terminal) session. In this case, the default SET
   GET-PUT-REMOTE AUTO setting should ensure that all "two-faced"
   commands like GET, PUT, REMOTE, HANGUP, BYE, etc, apply to the Kermit
   session, and all commands for the FTP session must include the FTP
   prefix. To be absolutely certain, you can use SET GET-PUT-REMOTE
   KERMIT.

  ftp foo.bar.baz.com
  if fail ...
  (log in)
  set host foo.bar.baz.com
  if fail ...
  (log in)

   Now you have both an FTP and Telnet connection to the same host (of
   course they could also be to different hosts, and you could also have
   a direct or dialed serial connection instead of a Telnet connection).
   Now assuming you have a Kermit server on the far end of the Kermit
   connection:

  rcd incoming      ; Changes Kermit server's directory (= REMOTE CD)
  ftp cd incoming   ; Changes FTP server's directory
  put oofa.txt      ; Sends a file on the Kermit connection
  ftp put oofa.txt  ; Sends a file on the FTP connection
  bye               ; Shuts down the Kermit connection
  ftp bye           ; Shuts down the FTP connection

   Note that PUT and SEND are synonyms for both FTP and Kermit
   connections.

   You can also establish dual sessions on the Kermit command line:

  kermit -j host1 -9 host2

   This makes a Telnet connection to host1 and an FTP connection to
   host2.

   [ [339]Top ] [ [340]FTP Top ] [ [341]C-Kermit Home ] [ [342]Kermit
   Home ]
     _________________________________________________________________

  3.10. Automating FTP Sessions

   Most of Kermit's scripting features can be used to make and control
   FTP sessions: FOR and WHILE loops, IF-ELSE and SWITCH constructions,
   variables, arrays, built-in functions, and all the rest. You can't use
   INPUT, MINPUT, OUTPUT, CLEAR, or SCRIPT on an FTP session, but these
   are not needed since the FTP protocol is well defined.

   [343]CLICK HERE for an FTP scripting tutorial.

    3.10.1. FTP-Specific Variables and Functions

   The following variable tells whether an FTP connection is open:

   \v(ftp_connected)
          1 if there is an active FTP connection, 0 if there isn't.

   The FTP OPEN command sets:

   \v(ftp_host)
          The host to which the most recent FTP connection was made.

   \v(ftp_security)
          The security method negotiated for the current FTP session. The
          value is "NULL" when no security is used. See [344]3.2. Making
          Secure FTP Connections.

   \v(ftp_server)
          The OS type (UNIX, VMS, etc) of the FTP server host.

   The FTP USER command (or FTP OPEN /USER:, or FTP with automatic login)
   sets:

   \v(ftp_loggedin)
          1 if you are logged in to an FTP server, 0 if you are not.

   The current COMMAND-PROTECTION-LEVEL and DATA-PROTECTION-LEVEL values
   are reflected in:

   \v(ftp_cpl)
   \v(ftp_dpl)
          The values are "clear", "confidential", "safe" or "private".
          See [345]3.2. Making Secure FTP Connections.

   The FTP GET-PUT-REMOTE setting is reflected in:

   \v(ftp_getputremote)
          The values are "auto", "ftp", or "kermit".

   Every FTP command sets the \v(success) variable, as well as the
   following two FTP-specific variables:

   \v(ftp_code)
          The standardized numeric FTP protocol code from the server's
          response to the last client command, a 3-digit decimal number
          defined in [346]RFC959. Briefly:

          1xx = Positive Preliminary Reply
          2xx = Positive Completion Reply
          3xx = Positive Intermediate Reply
          4xx = Transient Negative Completion Reply
          5xx = Permanent Negative Completion Reply

   \v(ftp_message)
          The text message, if any, from the server's response to the
          last client command. If the most recent response had multiple
          lines, this variable has only the final line. These messages
          are not standardized and vary in format and content from server
          to server. Synonym: \v(ftp_msg).

   FTP file transfers set the regular Kermit transfer status variables:

  \v(cps)         Characters per second of most recent transfer.
  \v(filespec)    File specification used in most recent transfer.
  \v(fsize)       Size of file most recently transferred.
  \v(tfsize)      Total size of file group most recently transferred.
  \v(xferstatus)  Status of most recent transfer (0 = success, 1 = failure).
  \v(tftime)      Elapsed time of most recent transfer, in seconds.

   During an FTP transfer, the per-file variables are:

  \v(filename)    Name of current file.
  \v(filenumber)  Ordinal file number in group (1, 2, 3, ...)
     _________________________________________________________________

    3.10.2. Examples

   Let's begin with a simple example showing how to log in, send some
   files, and log out:

  define error if fail { ftp bye, stop 1 Error: \%1 }
  set transact brief
  log t
  ftp ftp.xyzcorp.com /anonymous
  if fail stop 1 Connection failed
  if not \v(ftp_loggedin) stop 1 Login failed
  ftp cd incoming
  error {ftp cd}
  cd upload
  error {local cd}
  ftp put /delete *
  error {put}
  ftp bye

   First we define an error handling macro to be used after the
   connection is made. Then we set up a brief-format transaction log to
   keep a record of our file transfers. Then we make a connection to the
   host and log in anonymously. The "if fail" command checks whether the
   connection was made. The "if not" command checks whether login was
   successful. Obviously the script should not continue unless both tests
   succeed.

   Next we change to the server's 'incoming' directory and to our own
   'upload' directory, and send all the files that are in it (they can be
   any mixture of text and binary files), deleting each source file
   automatically after it is successfully uploaded. Each of these
   operations is checked with the ERROR macro, which prevents the script
   from continuing past a failure.

   Finally we close the FTP session with the "bye" command.

   Just like any other Kermit script, this one can be used in many ways:

     * It can be stored in a file, and Kermit can be told to TAKE the
       file.
     * In UNIX, it can be a "[347]kerbang" script and therefore run
       directly from the shell prompt or as a cron job.

   We could have used command shortcuts like "rcd", "put", and "bye", but
   since they can be ambiguous under certain circumstances, it is better
   to avoid them in scripts; they are intended mainly for convenience
   during interactive use. However, if you wish to use the shortcuts in a
   script, you can do it this way (error handling omitted for brevity):

  local \%t                       ; Declare a local temporary veriable
  assign \%t \v(ftp_getputremote) ; Save current FTP GET-PUT-REMOTE setting
  set ftp get-put-remote ftp      ; Choose FTP orientation
  ftp xyzcorp.com /anonymous      ; Open an FTP connection
  get oofa.txt                    ; GET a file
  put foo.bar                     ; PUT a file
  rdel yesterday.log              ; Delete a file on the server
  bye                             ; Log out and disconnect from server.
  set ftp get-put-remote \%t      ; Restore previous GET-PUT-REMOTE setting

   Of course, FTP scripts can also be written as macros. This lets you
   pass parameters such as hostnames, usernames, and filenames to them:

  define doftpget {
      if < \v(argc) 4 end 1 Usage: \%0 host user remotefile [ localfile ]
      ftp \%1 /user:\%2
      if fail end 1 FTP OPEN \%1 failed
      if not \v(ftp_loggedin) end 1 FTP LOGIN failed
      ftp get {\%3} {\%4}
      if fail end 1 FTP GET \%3 failed
      ftp bye
  }

   Add this definition to your Kermit customization file, and it will
   always be available when you start Kermit. This macro lets you
   download a file with FTP by giving a single command, e.g.:

  doftpget xyzcorp.com anonymous oofa.txt
     _________________________________________________________________

    3.10.3. Automating Secure FTP Sessions

   Often when making secure connections, you are prompted interactively
   for certain information or permission to proceed. These prompts can
   stop an automated procedure. To avoid them, you must give the
   appropriate commands to disable them, and/or supply the prompted-for
   information beforehand. Here are a few hints:

     * Make sure that SET TAKE ERROR and SET MACRO ERROR are both OFF.
       This is the default, but in case you have set either one of these
       ON in your script or initialization file, this makes the script
       halt on any kind of error. Normally you would want to check each
       operation for success or failure and take appropriate action.
     * On SSL and TLS connections, you may be asked whether it is OK to
       proceed with a connection to server that presents a self-signed
       certificate. You can use the SET AUTHENTICATION SSL (or TLS)
       VERIFY or SET AUTH SSL (or TLS) CERTS-OK commands to avoid this
       prompt by not requesting a certificate from the peer.
     * (More to be added...)

   [ [348]Top ] [ [349]FTP Top ] [ [350]FTP Script Tutorial ] [
   [351]C-Kermit Home ] [ [352]Kermit Home ]
     _________________________________________________________________

  3.11. Advanced FTP Protocol Features

   The remainder of the FTP documention (through the end of Section 3) is
   new to C-Kermit 8.0.206, but we leave it in black to prevent
   headaches. Except for titles.
     * [353]TERMINOLOGY
     * [354]FEATURE NEGOTIATION
     * [355]USING MGET: NLST VERSUS MLSD
     * [356]EXAMPLES
     * [357]REFERENCES

   The new releases of [358]C-Kermit (8.0.206) and [359]Kermit 95 (2.1)
   support new FTP protocol features from RFC 2389 as well as most of
   what's in the Elz and Hethmon Extensions to FTP Internet Draft (see
   [360]References). Some of these features, such as SIZE (request a
   file's size), MDTM (request file's modification time), and REST
   (restart interrupted transfer) have been widely implemented in FTP
   clients and servers for years (as well as in the initial release of
   the Kermit FTP clients). Others such as FEAT and MLSD are rarely seen
   and are new to the upcoming Kermit releases. TVFS (Trivial Virtual
   File Store) is supported implicitly, and the UTF-8 character-set is
   already fully supported at the protocol and data-interchange level.

   For Kermit users, the main benefit of the new FTP protocol extensions
   is the ability to do recursive downloads. But the extensions also
   introduce complications and tradeoffs that you should be aware of. Of
   course Kermit tries to "do the right thing" automatically in every
   case for backwards compatibility. But (as noted later) some cases are
   inherently ambiguous and/or can result in nasty surprises, and for
   those situations new commands and switches are available to give you
   precise control over Kermit's behavior, in case the defaults don't
   produce the desired results.
     _________________________________________________________________

   3.11.1. Terminology Command-line FTP clients such as Kermit (as well
   as the traditional FTP programs found on Unix, VMS, ..., even Windows)
   have commands like PUT, MPUT, GET, MGET, and BYE, which they convert
   into zero or more FTP protocol commands, such as NLST, RETR, QUIT. For
   clarity, we'll use "command" to refer to commands given by the user to
   the FTP client, and "directive" for FTP protocol commands sent by the
   FTP client to the FTP server.
     _________________________________________________________________

   3.11.2. Feature Negotiation New FTP protocol features are negotiated
   by the client sending a FEAT directive and the server responding with
   a list of (new) features it supports, or else with an error indication
   if it does not support the FEAT directive at all, in which case the
   client has to guess which new features it supports (Kermit guesses
   that it supports SIZE and MDTM but not MLST). Note that the MLST
   feature includes MLSD, which is not listed separately as a feature.

   Guessing is nice when it works, but sometimes it doesn't, and some FTP
   servers become confused when you send them a directive they don't
   understand, or they do something you didn't want, sometimes to the
   point of closing the connection. For this reason, Kermit lets you
   override default or negotiated features with the following new
   commands:

   FTP { ENABLE, DISABLE } FEAT
          Enables or disables the automatic sending of a FEAT directive
          upon connection to an FTP server. Note that
          FTP [ OPEN ] /NOINIT   also inhibits sending the FEAT directive
          (and several others) for the connection being OPEN'd, but
          without necessarily disabling FEAT for subsequent connections
          in the same Kermit instance. FEAT is ENABLED by default, in
          which case many FTP servers are likely to reply:

500 'FEAT': command not understood

          which is normally harmless (but you never know). (In C-Kermit
          8.0.208, this error message is suppressed unless you SET FTP
          DEBUG ON.)

   FTP ENABLE { MDTM, MLST, SIZE }
          Enables the given directive for implicit use by the FTP GET and
          MGET commands in case it has been disabled or erroneously
          omitted by the server in its FEAT response. Note: MLSD can be
          used in the FTP ENABLE and DISABLE commands as a synonym for
          MLST. YOU MUST GIVE THIS COMMAND AFTER MAKING THE FTP
          CONNECTION.

   FTP DISABLE { MDTM, MLST, SIZE }
          Disables implicit use of the given directive by GET or MGET in
          case it causes problems; for example, because it makes
          multifile downloads take too long or the server announces it
          erroneously or misimplements it. Use DISABLE FEAT before making
          a connection to prevent Kermit from sending the FEAT directive
          as part of its initial sequence. Note that disabling FEAT,
          SIZE, or MDTM does not prevent you from executing explicit FTP
          FEATURES, FTP SIZE, or FTP MODTIME commands. Also note that
          disabling SIZE prevents PUT /RESTART (recovery of interrupted
          uploads) from working. YOU MUST GIVE THIS COMMAND AFTER MAKING
          THE FTP CONNECTION.

   To enable or disable more than one feature, use multiple FTP ENABLE or
   FTP DISABLE commands. The SHOW FTP command shows which features are
   currently enabled and disabled.

   FTP FEATURES
          This command sends a FEAT directive to the server. In case you
          have been disabling and enabling different features, this
          resynchronizes Kermit's feature list with the server's. If the
          server does not support the FEAT directive, Kermit's feature
          list is not changed.

   FTP OPTIONS directive
          Informational only: the server tells what options, if any, it
          supports for the given directive, e.g. MLST. Fails if the
          server does not support the OPTS directive or if the directive
          for which options are requested is not valid. The directive is
          case-insensitive.

   FTP SIZE filename
          Sends a SIZE directive to the server for the given file. The
          filename must not contain wildcards. The server responds with
          an error if the file can't be found, is not accessible, or the
          SIZE directive is not supported, otherwise with the length of
          the file in bytes, which Kermit displays and also makes
          available to you in its \v(ftp_message) variable. If the
          directive is successful, Kermit (re-)enables it for internal
          use by the GET and MGET directives on this connection.

   FTP MODTIME filename
          Works just like the SIZE directive except it sends an MDTM
          directive. Upon success, the server sends modification
          date-time string, which Kermit interprets for you and also
          makes available in its \v(ftp_message) variable.

   Whenever a SIZE or MDTM directive is sent implicitly and rejected by
   the server because it is unknown, Kermit automatically disables it.
     _________________________________________________________________

   3.11.3. Using MGET: NLST versus MLSD When you give an MGET command to
   an FTP client, it sends a request to the FTP server for a list of
   files, and then upon successful receipt of the list, goes through it
   and issues a RETR (retrieve) directive for each file on the list (or
   possibly only for selected files).

   With the new FTP protocol extensions, now there are two ways to get
   the list of files: the NLST directive, which has been part of FTP
   protocol since the beginning, and the new MLSD directive, which is new
   and not yet widely implemented. When NLST is used and you give a
   command like "mget *.txt", the FTP client sends:

NLST *.txt

   and the server sends back a list of the files whose names match, e.g.

foo.txt
bar.txt
baz.txt

   Then when downloading each file, the client sends SIZE (if it wants
   have a percent-done display) and MDTM (if it wants to set the
   downloaded file's timestamp to match that of the original), as well as
   RETR (to retrieve the file).

   But when MLSD is used, the client is not supposed to send the filename
   or wildcard to the server; instead it sends an MLSD directive with no
   argument (or the name of a directory), and the server sends back a
   list of all the files in the current or given directory; then the
   client goes through the list and checks each file to see if it matches
   the given pattern, the rationale being that the user knows only the
   local conventions for wildcards and not necessarily the server's
   conventions. So with NLST the server interprets wildcards; with MLSD
   the client does.

     The interpretation of NLST wildcards by the server is not
     necessarily required or even envisioned by the FTP protocol
     definition (RFC 959), but in practice most clients and servers work
     this way. 

   The principal advantage of MLSD is that instead of sending back a
   simple list of filenames, it sends back a kind of database in which
   each entry contains a filename together with information about the
   file: type, size, timestamp, and so on; for example:

size=0;type=dir;perm=el;modify=20020409191530; bin
size=3919312;type=file;perm=r;modify=20000310140400; bar.txt
size=6686176;type=file;perm=r;modify=20001215181000; baz.txt
size=3820092;type=file;perm=r;modify=20000310140300; foo.txt
size=27439;type=file;perm=r;modify=20020923151312; foo.zip
(etc etc...)

   (If the format of the file list were the only difference between NLST
   and MLSD, the discussion would be finished: it would always be better
   to use MLSD when available, and the MGET user interface would need no
   changes. But there's a lot more to MLSD than the file-list format;
   read on...)

   The client learns whether the server supports MLSD in FEAT exchange.
   But the fact that the server supports MLSD doesn't mean the client
   should always use it. It is better to use MLSD:

     * On connections where the server imposes a time penalty for every
       command, e.g. the Red Hat Rawhide server. With MLSD, the client
       needs to send only one command (RETR) per file, whereas NLST
       requires three (SIZE, RETR, and MDTM). Suppose there is a
       30-second delay for each command and 1000 files are to be fetched;
       in that case, MLSD saves 60,000 seconds = 1000 minutes = 16 hours
       and 40 minutes.
     * For recursive downloads since there is no dependable way to
       download directory trees with NLST.

   But it is better to use NLST:

     * If you want only a couple short files out of a large directory. In
       this case, NLST is the better choice since the server sends a list
       of only the files you want, not a list of (say) a million files,
       which can make a big difference on slow connections. For example,
       suppose your wildcard matches three files of 1K each, but the
       million-file listing is 80MB long, and your connection is through
       a modem. The overhead of using MLSD is practically infinite.
     * If the server supports wildcarding features not known to the
       client, but that can be used to achieve desirable effects
       otherwise unobtainable, such as "[dir...]*.txt" in VMS or AOS/VS
       "except" clauses.
     * If you have been given a wildcard string by an FTP site
       administrator for fetching a specific group of files out of a
       larger directory, e.g. "mget ck[cuw]*.[cwh] makefile", that is
       expected to work with any client (an FTP site administrator can't
       be expected to know the wildcard syntax of every FTP client).

   But when using MLSD there are complications:

     * MLSD wants either a blank argument (meaning the current directory)
       or else the name of a specific directory. The client must not send
       it a wildcard or a filename.
     * But if the user's command is "mget xxx", how does the client know
       whether to send "xxx" in the MLSD directive? It might be the name
       of a directory on on the server, in which case it should be sent,
       or it might be the name of a file on the server (or a wildcard),
       in which case it must not be sent. Since the client knows its own
       wildcard syntax, then in most cases it would be right to send
       "MLSD" with no argument if xxx is wild, and to send "MLSD xxx" if
       it is not.
     * But suppose the server's file system allows filename characters
       that correspond with the client's wildcard syntax? For example:
       "[abc]" could be either a valid VMS directory name or a wildcard
       pattern used by the FTP client. What should the client do with
       "mget [abc]"? In this case there must be a way for the user to
       force sending the MGET argument as the MLSD argument.
     * If "xxx" is a regular file in the server's current directory,
       "mget xxx" works with NLST but not with MLSD.

   To further complicate matters, NLST can (in theory) work just like
   MLSD: if sent with a blank argument or a directory name, it is
   supposed to return a complete list of files in the current or given
   directory, which the client can match locally against some pattern. It
   is not known if any FTP server or client does this but nevertheless,
   it should be possible since this behavior can be inferred from RFC
   959.

   In view of these considerations, and given the need to preserve the
   traditional FTP client command structure and behavior so the software
   will be usable by most people:

    1. The MGET command should produce the expected result in the common
       cases, regardless of whether NLST or MLSD is used underneath.
    2. For anomalous cases, the user needs a way to control whether the
       MGET argument is sent to the server or kept for local use.
    3. At the same time, the user might need a way to send a directory
       name to the server, independent of any wildcard pattern.
    4. The user needs a way to force NLST or MLSD for a given MGET
       command.

   By default, Kermit's MGET command uses MLSD if MLST is reported by the
   server in its FEAT list. When MLSD is used, the filespec is sent to
   the server if it is not wild (according to Kermit's own definition of
   "wild" since it can't possibly know the server's definition). If the
   filespec is wild it is held for local use to select files from the
   list returned by the server. If MLST is not reported by the server or
   is disabled, Kermit sends the MGET filespec with the NLST directive.

   The default behavior can be overridden globally with FTP DISABLE MLST,
   which forces Kermit to use NLST to get file lists. And then for
   situations in which MLSD is enabled, the following MGET switches can
   be used to override the defaults for a specific MGET operation:

   /NLST
          Forces the client to send NLST. Example:

mget /nlst foo.*

   /MLSD
          Forces the client to send MLSD (even if MLST is disabled).
          Example:

mget /mlsd foo.*

   /MATCH:pattern
          When this switch is given, it forces the client to hold the
          pattern for local use against the returned file list. If a
          remote filespec is also given (e.g. the "blah" in "mget
          /match:*.txt blah"), then it is sent as the NLST or MLSD
          argument, presumably to specify the directory whose files are
          to be listed. When the /MATCH switch is not given, the MGET
          filespec is sent to the server if the directive is NLST or if
          the filespec is not wild. Examples:

  Command:                   With NLST:     With MLSD:
    mget                      NLST           MLSD
    mget *.txt                NLST *.txt     MLSD
    mget foo                  NLST foo       MLSD foo
    mget /match:*.txt         NLST           MLSD
    mget /match:*.txt foo     NLST foo       MLSD foo

   In other words, the pattern is always intepreted locally unless MGET
   uses NLST and no /MATCH switch was given.
     _________________________________________________________________

   3.11.4. Examples

  3.11.4.1. Downloading a Single File

   There are no choices here, just use the FTP GET command. Kermit always
   sends the RETR directive, and possibly SIZE and/or MDTM. The small
   advantage of using MLST in this case is outweighed by the risk and
   effort of coding a special case.

  3.11.4.2. Downloading a Group of Files from a Single Directory

   This case presents tradeoffs, especially on slow connections:

     * For downloading all or most of the files in a directory, MLSD is
       better because it eliminates the need to send SIZE and MDTM for
       each file. No special actions are required in this case; Kermit
       uses MLSD automatically if the server supports it (unless you have
       disabled it).
     * For a small number of files from a large directory, NLST is better
       because it bypasses downloading of a potentially huge file list
       prior to the files themselves. If you have a connection to a
       server that supports MLSD, use the /NLST switch to force NLST:

mget /nlst t[1234].h

     * If the server supports MLSD but does not support separate SIZE or
       MDTM directives, and you need the size and/or timestamp
       information, MLSD is better; no special actions required.
     * If the server supports MLSD but does not support the "size" and
       "modify" facts, but it does support the SIZE or MDTM directives,
       and you need the size and/or timestamp information, NLST is
       better.

  3.11.4.3. Downloading a Directory Tree

   MLSD is the only choice for recursive downloads; they rarely, if ever,
   work with NLST (the few cases where they do work rely on
   extra-protocol "secret" notations for the NLST argument). No special
   actions are required to force MLSD when the server supports it, unless
   you have disabled it. Examples:

   MGET /RECURSIVE
          This tells the server to send all files and directories in the
          tree rooted at its current directory.

   MGET /RECURSIVE *.txt
          This tells the server to send all *.txt files in the tree
          rooted at its current directory.

   MGET /MLSD /RECURSIVE *.txt
          Same as the previous example but forces Kermit to send MLSD in
          case it was disabled, or in case the server is known to support
          it even though it did not announce it in its FEAT listing.

   MGET /RECURSIVE /MATCH:*.zip archives
          Tells the server to send all ZIP files in the tree rooted at
          its "archives" directory.

   MGET /RECURSIVE /MATCH:* [abc]
          The server is running on VMS and you want it to send all the
          files in the directory tree rooted at [ABC]. But since "[abc]"
          looks just like a wildcard, you have to include a /MATCH:
          switch to force Kermit to send "[abc]" as the MLSD argument.

   In all cases in which the /RECURSIVE switch is included, the server's
   tree is duplicated locally.

     Although MLSD allows recursion and NLST does not, the MLSD
     specification places a heavy burden on the client; the obvious,
     straightforward, and elegant implementation (depth-first, the one
     that Kermit currently uses) requires as many open temporary files
     as the server's directory tree is deep, and therefore client
     resource exhaustion -- e.g. exceeding the maximum number of open
     files -- is a danger. Unfortunately MLSD was not designed with
     recursion in mind. (Breadth-first traversal could be problematic
     due to lack of sufficient navigation information.) 

   Of course all of Kermit's other MGET switches can be used too, e.g.
   for finer-grained file selection (by date, size, etc), for moving or
   renaming files as they arrive, to override Kermit's automatic per-file
   text/binary mode switching, to pass the incoming files through a
   filter, to convert text-file character sets, and so on.

  3.11.4.4. NLST/MLSD Summary Table

   Here's a table summarizing MGET behavior when the server supports both
   NLST and MLSD. /NLST and /MLSD switches are included for clarity to
   indicate which protocol is being used, and the expected effects. In
   practice you can omit the /NLST and /MLSD switches and the Kermit
   client chooses the appropriate or desired protocol as described above.
   Sample commands presume a Unix file system on the server, but of
   course the server can have any file system or syntax at all.

   User's Command FTP Sends Remarks
   mget /nlst NLST Gets a list of all the files in the server's current
   and downloads each file. The list includes names only, so Kermit also
   must send SIZE and MDTM directives if size and timestamp information
   is required (this is always true of NLST). Sending NLST without an
   argument is allowed by the RFC959 NLST definition and by the Kermit
   FTP client, but might not work with other clients, and also might not
   work with every server.
   mget /nlst foo NLST foo If "foo" is a directory, this gets a list of
   all the files from the server's "foo" directory and downloads each
   file; otherwise this downloads the file named "foo" (if any) from the
   server's current directory.
   mget /nlst *.txt NLST *.txt Gets a list of the files in the server's
   current directory whose names match the pattern *.txt, and then
   downloads each file from the list. Because we are using NLST, we send
   the filespec (*.txt) to the server and the server interprets any
   wildcards.
   mget /nlst foo/*.txt NLST foo/*.txt  Gets a list of the files in the
   server's "foo" directory whose names match the pattern *.txt, and then
   downloads each file from the list (server interprets wildcards).
   mget /nlst /match:*.txt NLST Gets a list of all the files in the
   server's current directory and then downloads each one whose name
   matches the pattern *.txt (client interprets wildcards).
   mget /nlst /match:*.txt foo  NLST foo Gets a list of all the files in
   the server's "foo" directory and then downloads each one whose name
   matches the pattern *.txt (client interprets wildcards).
   mget /mlsd MLSD Gets a list of all the files from the server's current
   directory and then downloads each one. The list might include size and
   timestamp information, in which case Kermit does not need to send SIZE
   and MDTM directives for each file (this is always true of MLSD).
   mget /mlsd foo MLSD foo Gets a list of all the files from the server's
   "foo" directory (where the string "foo" does not contain wildcards)
   and then downloads each one. If "foo" is a regular file and not a
   directory, this command is supposed to fail, but some servers have
   been observed that send the file.
   mget /mlsd *.txt MLSD Gets a list of all the files from the server's
   current directory and then downloads only the ones whose names match
   the pattern "*.txt". Because we are using MLSD and the MGET filespec
   is wild, we do not send the filespec to the server, but treat it as
   though it had been given in a /MATCH: switch and use it locally to
   match the names in the list.
   mget /mlsd foo/*.txt MLSD This one won't work because MLSD requires
   that the notions of server directory and filename-matching pattern be
   separated. However, the client, which can't be expected to know the
   server's file-system syntax, winds up sending a request that the
   server will (or should) reject.
   mget /mlsd /match:*.txt MLSD Gets a list of all the files from the
   server's current directory and then downloads only the ones whose
   names match the pattern "*.txt" (client interprets wildcards).
   mget /mlsd /match:*.txt foo MLSD foo If "foo" is a directory on the
   server, this gets a list of all the files from the server's "foo"
   directory and then downloads only the ones whose names match the
   pattern "*.txt" (client interprets wildcards). This leaves the server
   CD'd to the "foo" directory; there's no way the client can restore the
   server's original directory because MLSD doesn't give that
   information, and since the client can not be expected to know the
   server's file-system syntax, it would not be safe to guess. If "foo"
   is a regular file, MLSD fails.
   mget /mlsd foo bar MLSD This one is problematic. You're supposed to be
   able to give MGET a list a filespecs; in this case we name two
   directories. The client must change the server's directory to "foo" to
   get the list of files, and then the files themselves. But then it has
   no way to return to the server's previous directory in order to do the
   same for "bar", as explained in the previous example.
   mget /mlsd /match:* [abc] MLSD [abc] Including a /MATCH: switch forces
   [abc] to be sent to the server even though the client would normally
   think it was a wildcard and hold it for local interpretation. In this
   example, [abc] might be a VMS directory name.
   mget /mlsd /match:* t*.h MLSD t*.h Contrary to the MLSD specification,
   some MLSD-capable FTP servers do interpret wildcards. This form of the
   MGET command can be used to force a wildcard to be sent to the server
   for interpretation.

   When MLSD is used implicitly (that is, without an /MLSD switch given
   to force the use of MLSD) and an MGET command such as "mget foo/*.txt"
   fails, Kermit automatically falls back to NLST and tries again.
     _________________________________________________________________

   3.11.5. References

    1. Postel, J., and J. Reynolds, File Transfer Protocol (FTP), RFC
       959, October 1985: [361]ftp://ftp.isi.edu/in-notes/rfc959.txt.
    2. Hethmon, P, and R. Elz, Feature negotiation mechanism for the File
       Transfer Protocol, RFC 2389, August 1998:
       [362]ftp://ftp.isi.edu/in-notes/rfc2389.txt.
    3. Elz, R, and P. Hethmon, Extensions to FTP, Internet Draft
       draft-ietf-ftpext-mlst-16.txt, September 2002:
       [363]http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-16
       .txt.
    4. [364]The Kermit FTP Client (overview).

   [ [365]Top ] [ [366]FTP Top ] [ [367]C-Kermit Home ] [ [368]Kermit
   Home ]
  __________________________________________________________________________

4. FILE SCANNING

   A new feature called file scanning is used in various contexts to
   determine if a file is text or binary, and if it is text, what kind of
   text. The overhead of file scanning is surprisingly tolerable, usually
   about a quarter second per file. File scanning is now used instead of
   filename patterns unless you SET FILE SCAN OFF, which restores the
   previous behavior.

   The primary benefit of file scanning is in file transfer. For all
   practical purposes, now you can stop worrying about whether a file
   should be sent in binary or text mode, or about sending mixtures of
   text and binary files in a single operation, or configuring and
   fine-tuning your lists of binary-file and text-file name patterns: now
   it all just works.

   File scanning is done by the file sender, which determines the type of
   each file before it sends it and informs the receiver (Kermit or FTP
   server) of the type. File scanning is NOT done by the receiver,
   because it is the sender's responsibility to determine each file's
   type, send the file in the right mode, and inform the receiver of the
   mode. If both transfer partners are capable of this (or any other)
   form of automatic text/binary mode switching, then files can be sent
   in both directions with no worries about corruption due to
   inappropriate transfer mode. (As noted in [369]Section 3, FTP servers
   don't do this, so this discussion does not apply when using Kermit to
   download from an FTP server.)

   The rest of this section is mainly for the curious. If you don't read
   it and simply accept all defaults, every file you send should go in
   the appropriate mode automatically. As always, however, for
   character-set translation to work for 7- and 8-bit character-set
   files, the appropriate SET FILE CHARACTER-SET command(s) must have
   been executed to identify their encoding (Kermit's default file
   character-set is neutral ASCII except on platforms like HP-UX or
   DG/UX, where the default file character-set is known). And of course,
   receiving is another matter -- obviously the other Kermit must also
   send each file in the appropriate mode.

   Scanning is more reliable than filename patterns simply because
   filenames are not reliable indicators of the file's contents. Classic
   examples include ".doc" files, which are binary if Microsoft Word
   documents but text on most other platforms, and ".com" files, which
   are binary on DOS and Windows but text on VMS. Anyway, nobody knows
   the naming conventions (if any) of all the applications (and persons!)
   on your computer. Scanning, on the other hand, determines each file's
   type by inspecting its contents rather than just looking at its name.

   Also, file patterns -- even when they work as intended -- categorize
   each file only as text or binary, whereas file scanning can make finer
   distinctions:

   BINARY
          Binary data, not to be converted in any way. Examples include
          binary machine code (executable programs), graphics images
          (GIF, JPG, etc), compressed files (Z, GZ, etc), archives and
          packages (ZIP, TAR, RPM, etc), object files and libraries (OBJ,
          DLL, etc).

   7-BIT TEXT
          Text encoded in a 7-bit character set such as ASCII or one of
          the ISO 646 national versions. Kermit has no way to tell which
          character is used, only that it's 7-bit text. Typical examples
          include program source code, README files, Perl or Kermit
          scripts, plain-text email, HTML, TeX, and various textual
          encodings of binary files: Hex, Base64, etc. When sending such
          files, the FILE DEFAULT 7BIT-CHARACTER-SET is used as the file
          character-set, and then the appropriate transfer character set
          is chosen from the associations list (ASSOCIATE, SHOW
          ASSOCIATIONS).

   8-BIT TEXT
          Text encoded in an 8-bit character set such as Latin-1,
          Latin-2, Latin/Hebrew, Latin/Cyrillic, KOI8, HP-Roman8, JIS X
          0208, Code Page 437, or Code Page 1252. Again, Kermit has no
          way of knowing which particular set is in use, only that it's
          8-bit text. When sending such files, the FILE DEFAULT
          8BIT-CHARACTER-SET is used as the file character-set, and then
          the appropriate transfer character set is chosen from the
          associations list.

   UCS2 TEXT
          Unicode in its basic form, 16 bits (2 octets) per character.
          When sending such files, UCS2 is the file character-set and the
          byte order is identified automatically; the appropriate
          transfer character set is chosen from the associations list.
          Normally this would be UTF8. UTF-16 is not supported yet;
          Kermit's Unicode translations are restricted to Plane 0, the
          Base Multilingual Plane (BMP).

   UTF8 TEXT
          Unicode in its 8-bit transformation format. When sending such
          files, UTF8 is the file character-set; the appropriate transfer
          character set is chosen from the associations list, normally
          UCS2 or UTF8.

   File scanning is available in UNIX C-Kermit, in K-95, and to a limited
   extent, in VMS C-Kermit (full scanning is problematic in VMS because
   even plain-text files might contain binary record-format information).
   The relevant commands are:

   SET TRANSFER MODE { AUTOMATIC, MANUAL }
          Tells whether the file-transfer mode (text or binary) should be
          set by automatic or "manual" means. AUTOMATIC is the default,
          which allows any of the automatic methods that are enabled to
          do their jobs: FILE SCAN, FILE PATTERNS, peer recognition, etc.
          MANUAL lets you control the transfer mode with the SET FILE
          TYPE commands. As always, /TEXT and /BINARY switches on your
          file-transfer commands override all other methods; if you give
          one of these switches, scanning is not done. SHOW TRANSFER
          displays the current TRANSFER MODE setting.

   SET FILE SCAN { ON [ number ], OFF }
          Turns this feature on and off. It's ON by default. When OFF,
          the previous rules apply (SET FILE PATTERNS, etc). When ON is
          given, you can also specify a number of bytes to be scanned.
          The default is 49152 (= 48K). If a negative number is given,
          the entire file is scanned, no matter how big, for maximum
          certainty (for example, a PostScript file that appears to be
          plain text might include an embedded graphic past the normal
          scanning limit). SHOW FILE displays the current FILE SCAN
          setting.

   SET FILE DEFAULT 7BIT-CHARACTER-SET name
          Tells the 7-bit character-set to use if scanning identifies a
          7-bit text file, e.g. GERMAN. SHOW FILE displays the current
          SET FILE DEFAULT settings. So does SHOW CHARACTER-SETS.

   SET FILE DEFAULT 8BIT-CHARACTER-SET name
          Tells the 8-bit character-set to use if scanning identifies an
          8-bit text file, e.g. LATIN1. SHOW FILE and SHOW CHARACTER-SET
          display this.

   ASSOCIATE FILE-CHARACTER-SET fcs tcs
          When sending files and a file character-set (fcs) is identified
          by scanning, this tells C-Kermit which transfer character-set
          (tcs) to translate it to. It also allows C-Kermit to set the
          appropriate transfer character-set automatically whenever you
          give a SET FILE CHARACTER-SET command.

   ASSOCIATE TRANSFER-CHARACTER-SET tcs fcs
          When receivinging files and a file arrives whose transfer
          character-set (tcs) is announced by the sender, this command
          tells C-Kermit which file character-set (fcs) to translate it
          to. It also allows C-Kermit to set the appropriate file
          character-set whenever you give a SET TRANSFER CHARACTER-SET
          command.

   SET FILE CHARACTER-SET name
          When given for a 7-bit set, also sets FILE DEFAULT
          7BIT-CHARACTER-SET to the same set. When given for an 8-bit
          set, also sets FILE DEFAULT 8BIT-CHARACTER-SET to the same set.
          If an ASSOCIATE FILE-CHARACTER-SET command has been given for
          this set, also sets the corresponding transfer character-set.

   DIRECTORY /XFERMODE [ filespec ]
          Performs a file scan of the given files, listing the result for
          each file. If FILE SCAN is OFF but PATTERNS are ON, the result
          shown according to the current FILE TEXT-PATTERNS and
          BINARY-PATTERNS, and are restricted to (B) and (T). When FILE
          SCAN is ON, the results are:

  (B)          Binary
  (T)(7BIT)    Text: 7-bit
  (T)(8BIT)    Text: 8-bit
  (T)(UTF8)    Text: Unicode UTF8
  (T)(UCS2BE)  Text: Unicode UCS2 Big Endian
  (T)(UCS2LE)  Text: Unicode UCS2 Little Endian

          So you can use DIR /XFER to get a preview of how each file in a
          selected group will be transferred. Everything to the right of
          the (B) or (T) is new. If FILE SCAN is OFF, you only get the
          (B) or (T) as before.

          Note: Big and Little Endian refer to the ordering of bytes
          within a computer word. Big Endian architecture is standard and
          is used on most non-PC computers. Little Endian architecture is
          used on PCs.

   To illustrate file-transfer with scanning, suppose you have a
   directory containing a mixture of text and binary files, and each text
   file can be 7-bit German ISO 646, 8-bit Latin-1, or Unicode in any of
   the following forms: UCS2 Little Endian, UCS2 Big Endian, or UTF8
   ([370]UTF-16 is not supported yet). Assuming all the built-in defaults
   are in effect, the following three commands do the job:

  set file char german   ; This sets the default for 7-bit text files
  set file char latin1   ; This sets the default for 8-bit text files
  send *

   Each file is sent in the appropriate mode (text or binary), with text
   files converted to the appropriate transfer character-set and labeled
   so the receiver can convert them according to its own local
   conventions.

   By the way, what if you want to inhibit character-set translation but
   still allow automatic text/binary mode switching? Previously, you
   could simply SET TRANSFER CHARACTER-SET TRANSPARENT. But now with file
   scanning, the file and transfer character-sets are set automatically
   per file. A new command was added for this purpose:

   SET TRANSFER TRANSLATION { ON, OFF }
          Enables and disables file-transfer character-set translation.
          It is enabled by default.

   When TRANSFER TRANSLATION is OFF but FILE SCAN is ON, files are still
   scanned to see if they are text or binary, but no character-set
   translation is done when they text: only the normal record-format
   conversion.

   Like all SET commands, SET TRANSFER TRANSLATION is global and
   persistent. You can also force a particular file-transfer command
   (SEND, MSEND, GET, RECEIVE, TRANSMIT, etc) to not translate without
   affecting the global translation settings by including the new
   /TRANSPARENT switch, e.g.

  send /transparent oofa.txt

   As of C-Kermit 8.0.206, SET TRANSFER CHARACTER-SET TRANSPARENT implies
   SET TRANSFER TRANSLATION OFF.

   File scanning is also used in the TYPE command. The source file type
   and character set are determined as above, and then the file is
   automatically converted to your display character-set, line by line.
   In Kermit 95, the display character-set is Unicode, perhaps converted
   to your current console code page; in other versions of C-Kermit, it
   is your current file character-set. Thus if you have the following set
   appriately:

  SET FILE CHARACTER-SET (necessary in Unix but not K95)
  SET FILE DEFAULT 7BIT CHARACTER-SET
  SET FILE DEFAULT 8BIT CHARACTER-SET

   then you should be able to TYPE any text file and see something
   reasonable. For example, in Unix, if your DEFAULT 7BIT-CHARACTER-SET
   is ITALIAN and your DEFAULT 8BIT-CHARACTER-SET is LATIN1, and your
   FILE CHARACTER-SET is LATIN1, you can TYPE an Italian ISO 646 file, a
   Latin-1 file, or any kind of Unicode file, and have it translated
   automatically to Latin-1 for your display.

   In the GUI version of Kermit 95, you can see mixtures of many
   different scripts if the file is UTF8 or UCS2: Roman, Cyrillic,
   Hebrew, Greek, Armenian, Georgian, etc, all on the same screen at
   once.

   File scanning also adds a new criterion for file selection, i.e. to
   select only text (or binary) files. Several commands now include a new
   switch, /TYPE:{BINARY,TEXT,ALL}. BINARY means select only binary
   regular files (not directories). TEXT means select only text files.
   ALL means don't scan; select all files. Examples:

   SEND /TYPE:BINARY *.*
          Sends only binary files, skipping over text files.

   NOTE: File scanning is NOT done when using external protocols (because
   the external protocol programs, such as sz, are processing each file,
   not Kermit).

   DIRECTORY /TYPE:TEXT
          Lists only text files but not binary files.

   DELETE /TYPE:BINARY foo.*
          Deletes all foo.* files that are regular binary files but does
          not delete any text files.

   CHMOD /TYPE:BINARY 775 *
          (UNIX) Changes the permissions of all binary files to 775.

   When FILE SCAN is OFF and FILE PATTERNS are ON, behavior is as before
   with PATTERNS ON, but with some improvements:

     * Pathnames are now stripped prior to pattern matching.
     * Backup suffixes (like .~3~) are stripped prior to pattern
       matching.

   [ [371]Top ] [ [372]Contents ] [ [373]C-Kermit Home ] [ [374]Kermit
   Home ]
  __________________________________________________________________________

5. FILE AND DIRECTORY NAMES CONTAINING SPACES

   Prior to the introduction of the graphical user interface (GUI), it
   was inconceivable that file or directory names could contain spaces,
   because space is a field delimiter in all command languages. GUIs,
   however, use dialog boxes for filenames, so there is never any
   question of distinguishing a filename from adjacent fields -- because
   there are no adjacent fields -- and therefore it has become quite
   common on computers that have GUIs to have file and directory names
   composed of multiple words. Of course this poses problems for command
   shells and other text-oriented programs.

   Most command shells address these problems by allowing such names to
   be enclosed in doublequotes, e.g.:

  cd "c:\Program Files"

   C-Kermit previously used braces for this:

  cd {c:\Program Files}

   which was not what most people expected. And even when braces were
   used, Kermit had difficulties with completion, file menus, and so
   forth, within braced fields.

   C-Kermit 8.0 allows either doublequotes or braces to be used for
   grouping:

  send "this file"
  send {this file}
  rename "this file" "that file"
  rename {this file} "that file"
  rename "this file" {that file}
  cd {Program Files}
  cd "Program Files"

   Note that the doublequotes or brackets must enclose the whole file or
   directory specification:

  "c:\My Directory"

   not:

  c:\"My Directory"

   In C-Kermit 8.0, you can also use completion on these filenames, in
   which case Kermit supplies the quotes (or braces) automatically.
   Example (in which the current directory contains only one file whose
   name starts with "th" and its full name is "this file" (without the
   quotes, but with the space)):

  cat th<Tab>

   Kermit repaints the filename field like this:

  cat "this file"

   That is, it backspaces over the original "th" and then writes the
   filename in doublequotes.

   If completion is only partial, Kermit still supplies the quotes, but
   in this case also beeps. To continue the filename, you must first
   backspace over the closing quote. The closing quote is supplied in
   this case to make sure that you can see the spaces, especially if they
   are trailing. For example, if the current directory contains two files
   whose names start with "th", and their fill names are "this file" and
   "this other file":

  cat th<Tab>

   Kermit prints:

  cat "this "<Beep>

   If it didn't print the closing quote, you would probably wonder why it
   was beeping.

   Also, if you begin a filename field with a doublequote or opening
   brace, now you can use completion or get ?-help; this was never
   possible before.

 C-Kermit>type "thi? Input file specification, one of the following:
   this file        this other file
 C-Kermit>type "thi_

   [ [375]Top ] [ [376]Contents ] [ [377]C-Kermit Home ] [ [378]Kermit
   Home ]
  __________________________________________________________________________

6. OTHER COMMAND PARSING IMPROVEMENTS

  6.1. Grouping Macro Arguments

   Doublequotes now can be used in macro invocations to group arguments
   containing spaces, where previously only braces could be used:

  define xx show args
  xx one "this is two" three

   Result:

  Macro arguments at level 0 (\v(argc) = 4):
   \%0 = xx
   \%1 = one
   \%2 = this is two
   \%3 = three

   Also, you can now quote braces and quotes in macro args (this didn't
   work before). Examples:

  xx "{"  ; The argument is a single left brace
  xx {"}  ; The argument is a doublequote character

   In case this new behavior interferes with your scripts, you can
   restore the previous behavior with:

  SET COMMAND DOUBLEQUOTING OFF

  6.2. Directory and File Name Completion

   C-Kermit 8.0 also includes better completion for directory names, e.g.
   in the CD command. If the name typed so far uniquely matches a
   directory name, it is completed (as before), but now if the directory
   contains any subdirectories, completion is partial (allowing you to
   supply additional path segments without backspacing); otherwise it is
   complete.

   Completion has also been improved for file and directory names that
   contain not only spaces (as described above) but also "metacharacters"
   such as asterisk (*) and tilde (~): now the field is repainted if
   necessary. For example, if the current directory contains only one
   file whose name contains "blah", then in:

  type *blah<Tab>

   "*blah" is replaced by the filename. In earlier releases, the part
   typed so far was left on the command line (and in the history buffer),
   so even when the original command worked, the recalled version would
   not. Similarly for ~ (the nearly-universal Unix notation for
   username):

  type ~olga/x<Tab>

   is repainted as (e.g.):

  type /users/home/olga/x(Beep)

   Speaking of command history, the new SHOW HISTORY command shows your
   command history and recall buffer. SAVE COMMAND HISTORY saves it into
   a file of your choice.

  6.3. Passing Arguments to Command Files

   The method for passing arguments to command files has been improved.
   Prior to C-Kermit 7.0 there was no provision for doing this. In
   C-Kermit 7.0, the TAKE command was changed to allow arguments to be
   given after the filename:

  take commandfile arg1 arg2 ...

   This was accomplished by replacing the current \%1, \%2, etc, with the
   given arguments, since a new set of macro argument variables is
   created only when a macro is executed, not a command file. It is much
   more intuitive, however, if arguments to command files worked like
   those to macros: the command file sees the arguments as its own \%1,
   \%2, etc, but the caller's variables are not disturbed. C-Kermit 8.0
   accomplishes this by automatically creating an intermediate temporary
   macro to start the command file (if any arguments were given), thus
   creating a new level of arguments as expected.

  6.4. More-Prompting

   The familiar --more?-- prompt that appears at the end of each
   screenful of command-response output now accepts a new answer: G (Go)
   meaning "show all the rest without pausing and asking me any more
   questions". P (Proceed) is a synonym for G.

  6.5. Commas in Macro Definitions

   As noted in the [379]C-Kermit manual, comma is used to separate
   commands in a macro definition. Even when the macro is defined on
   multiple lines using curly-brace block-structure notation without
   commas, the definition is still stored internally as a comma-separated
   list of commands. Therefore special tricks are needed to include a
   comma in a command. The classic example is:

  define foo {
      (some command)
      if fail echo Sorry, blah failed...
  }

   This would result in Kermit trying to execute a "blah" command. This
   could always be handled by enclosing the text in braces:

  define foo {
      (some command)
      if fail echo {Sorry, blah failed...}
  }

   but doublequotes (more intuitive) should have worked too. Now they do:

  define foo {
      (some command)
      if fail echo "Sorry, blah failed..."
  }

  6.6. Arrow Keys

   As of version 8.0.201, C-Kermit on most platforms lets you access the
   command history buffer with arrow keys, just as you always could with
   control characters. The restrictions are:

    1. Only Up and Down arrow keys are accepted.
    2. Only 7-bit ANSI arrow-key sequences are understood (ESC followed
       by [ or uppercase letter O, followed by uppercase letter A or (up)
       B (down).

   This change was made to facilitate command recall in Linux-based PDAs
   that don't have a Control key, or at least not one that's easily (or
   always) accessible, such as the Sharp Zaurus SL5500.

   [ [380]Top ] [ [381]Contents ] [ [382]C-Kermit Home ] [ [383]Kermit
   Home ]
  __________________________________________________________________________

7. NEW COMMANDS AND SWITCHES

   See [384]Section 4 for more about file scanning and the /TYPE: switch.

   ASK[Q] [ /TIMEOUT:number /QUIET /DEFAULT:text ] variable [ prompt ]
          The new optional /TIMEOUT: switch for ASK and ASKQ causes the
          command to time out and and fail if no response is given within
          the specified number of seconds, 1 or greater (0 or less means
          no timeout, wait forever). This works just like SET ASK-TIMER,
          except its effect is local to the ASK command with which it is
          given and it does not disturb the global ask timer setting. The
          new /QUIET switch tells Kermit not to print an error message if
          the ASK or ASKQ command times out waiting for a response.

          Version 8.0.211 adds the /DEFAULT:text switch for ASK-Class
          commands (ASK, ASKQ, and GETOK). This lets you supply a default
          answer in case the user supplies an empty answer or the
          /TIMEOUT: switch was included and the time limit expired
          without an answer. In both these cases, the command succeeds.

   CAT filename
          Equivalent to TYPE /NOPAGE.

   CDUP
          Changes Kermit's local working directory to the parent of the
          current one. Equivalent to "cd .." in UNIX or Windows, "cd [-]"
          in VMS, "cd ^" in AOS/VS, etc; in other words, it's a
          platform-independent way of moving one level up in a directory
          tree.

   CHMOD [ switches ] permission files
          UNIX only. Sets file permissions for one or more files or
          directories. The permission must be given as an octal number,
          e.g. 664, 755. Switches: /DIRECTORIES, /FILES, /NOLIST, /PAGE,
          /DOTFILES, /LIST, /NOPAGE, /RECURSIVE, /TYPE:{TEXT,BINARY,ALL},
          /SIMULATE. The /TYPE: switch allows selection of only text or
          binary files. For example, if you have a mixture of source
          files and executables, you can use "chmod /files /type:text
          664" to give owner/group read/write and world read permission
          to the text files, and "chmod /files /type:binary 775" to give
          the same plus execute permission to the executables. Use
          /SIMULATE to see which files would be affected, without
          actually changing their permissions.

   CLEAR KEYBOARD-BUFFER
          Flushes any as-yet unread characters from the keyboard input
          buffer. Useful for flushing typeahead in scripts.

   CONTINUE
          When given at an interactive command prompt that was reached by
          issuing a PROMPT command (described in this section) from a
          script, this command returns to the script, continuing its
          execution at the command after the PROMPT command. In this
          context, CONTINUE is simply a more-intuitive synonym for END.

   COPY, RENAME, and TRANSLATE
          These commands now work on file groups if the target filename
          is a directory, e.g. "copy oofa.* ..", "rename * ~olga/tmp/"

   COPY /APPEND source destination
          The source file specification can now include wildcards, in
          which case all of the source files that match will go into the
          destination file in alphabetical order by name.

   DELETE /ASK
          Asks permission to delete each file before deleting it. In
          C-Kermit 7.0, the answers were "yes" (or "ok") and "no".
          C-Kermit 8.0 adds "go" (meaning, delete all the rest without
          asking) and "quit" (cancel the DELETE command and return to the
          prompt).

   DELETE /DIRECTORIES
          Deletes not only files but also directories.

   DELETE /RECURSIVE
          Deletes all files that match the given file specification in
          the current (or given) directory and all directories beneath
          it.

   DELETE /SUMMARY
          Prints only the number of files deleted and total size freed,
          without listing each file.

   DELETE /TREE
          Shorthand for DELETE /RECURSIVE /DIRECTORIES /DOTFILES/.
          Equivalent to Windows DELTREE or Unix "rm -Rf". If no file
          specification is given, the contents of the current directory,
          plus all of its subdirectories and their contents, are deleted.

   DELETE /TYPE:BINARY
          Delete only regular binary files (requires FILE SCAN ON).

   DELETE /TYPE:TEXT
          Delete only regular text files (requires FILE SCAN ON).

   DIRECTORY [ switches ] [ filespec [ filespec [ filespec ... ] ] ]
          The DIRECTORY command now accepts more than one file
          specification; e.g. "directory moon.txt sun.doc stars.*".

   DIRECTORY /NORECURSIVE xxx
          If xxx is a directory name, forces listing of the directory
          itself rather than its contents.

   DIRECTORY /FOLLOWLINKS xxx
          (UNIX only) Tells the DIRECTORY command to follow symbolic
          links. This not the default because it can cause endless loops.

   DIRECTORY /NOFOLLOWLINKS xxx
          (UNIX only) Tells the DIRECTORY command not to follow symbolic
          links, but rather, merely to list them. This is the default.

   DIRECTORY /OUTPUT:filename
          Sends the results of the DIRECTORY command to the given file.

   DIRECTORY /SUMMARY
          Prints only the number of directories and files and the total
          size, without listing each file.

   DIRECTORY /TYPE:{TEXT,BINARY}
          Shows only files of the selected type, based on file scan.

   DIRECTORY /XFERMODE
          Now shows results of file scan (see [385]Section 4).

   FOPEN [ switches ] channel filename

          As of version 8.0.211, FOPEN allows /dev/tty as a filename in
          Unix-based operating systems.

   FREAD /TRIM
          (8.0.211) Trims any trailing blanks or tabs from the item (such
          as a line of text) that it has read.

   FREAD /UNTABIFY
          (8.0.211) Converts Horizontal Tab characters to the appropriate
          number of spaces, based on VT100-like tab stops
          (1,9,17,25,...).

   GREP [ switches ] pattern files
          Similar to Unix grep command: displays file lines that match
          the given [386]pattern. Switches:

        /COUNT[:variable]
                Don't show the matching lines, just tell how many lines
                match. If a variable name is specified, the count is
                stored in the given variable.

        /DOTFILES
                Include files whose names begin with dot.

        /LINENUMBERS
                Show line numbers of matching lines.

        /NAMEONLY
                only list the names of files that contain matching lines,
                but not the lines themselves.

        /NOBACKUP
                Skip backup files.

        /NOCASE
                Ignore alphabetic case while pattern matching.

        /NODOTFILES
                skip files whose names start with dot (period).

        /NOLIST
                Suppress output but set SUCCESS or FAILURE according to
                search result.

        /NOMATCH
                Look for lines that do not match the pattern.

        /NOPAGE
                Don't pause between screens of output.

        /OUTPUT:filename
                Write results into the given file.

        /PAGE
                Pause between screens of output.

        /RECURSIVE
                Search files in subdirectories too.

        /TYPE:{TEXT,BINARY}
                Search only files of the specified type.

          Synonyms: FIND, SEARCH.

   GETOK /TIMEOUT:n /QUIET /DEFAULT:text
          The new /QUIET switch instructs GETOK, when given a timeout,
          not to print an error message if it times out. As of 8.0.211, a
          default answer can be supplied (see ASK).

   HEAD [ switches ] filename
          Equivalent to TYPE /HEAD [ other-switches ] filename.

   HELP DATE
          Explains date-time formats, including timezone notation and
          delta times.

   HELP FIREWALLS
          Explains the firewall negotiation capabilities of your version
          of Kermit.

   KCD [ symbolic-directory-name ]
          Changes Kermit's working directory to the named symbolic
          directory, such as such as exedir, inidir, startup, download,
          or and home. Type "kcd ?" for a list of symbolic directory
          names known to your copy of Kermit, or give the new ORIENTATION
          command for a more detailed explanation. If you give a KCD
          command without a directory name, Kermit returns to its "home"
          directory, which is determined in some way that depends on the
          underlying operating system, but which you can redefine with
          the (new) SET CD HOME command. Your home directory is shown by
          SHOW CD and it's also the value of the \v(home) variable.

   LICENSE
          Displays the C-Kermit license.

   L-commands
          When Kermit has a connection to a Kermit or FTP server, file
          managment commands such as CD, DIRECTORY, and DELETE might be
          intended for the local computer or the remote server. C-Kermit
          8.0.200 and earlier always executes these commands on the local
          computer. If you want them executed by the remote server, you
          have to prefix them with REMOTE (e.g. REMOTE CD) or use special
          R-command aliases (e.g. RCD = REMOTE CD, RDIR = REMOTE DIR,
          etc). But this feels unnatural to FTP users, who expect
          unprefixed file management commands to be executed by the
          remote server, rather than locally. C-Kermit 8.0.201 adds
          automatic locus switching to present an FTP-like interface for
          FTP connections and the normal Kermit interface for Kermit
          connections, and a SET LOCUS command (described below) to
          control whether or how this is done. For when LOCUS is REMOTE,
          a new set of commands was added for local management: LCD
          (Local CD), LDIR (Local DIR), etc. These are described below
          under SET LOCUS.

   MORE filename
          Equivalent to TYPE /PAGE.

   ORIENTATION
          Displays symbolic directory names and the corresponding
          variable names and values. The symbolic names, such as exedir,
          inidir, startup, download, and home, can be used as arguments
          to the new KCD command.

   PROMPT [ text ]
          For use in a macro or command file: enters interactive command
          mode within the current context ([387]Section 8.1). If the
          optional text is included, the prompt is set to it. The text
          can include variables, functions, etc, as in the SET PROMPT
          command. They are evaluated each time the prompt is printed.
          Unlike the SET PROMPT command, the text argument applies only
          to the current command level. Thus you can have different
          prompts at different levels.

   REMOTE SET MATCH { DOTIFILE, FIFO } { ON, OFF }
          Allows the client to tell the server whether wildcards sent to
          the server should match dot files (files whose names begin with
          period) or FIFOs (named pipes). See SET MATCH.

   SET ATTRIBUTE RECORD-FORMAT { ON, OFF }
          Allows control of the Kermit's Record-Format attribute. Set
          this to OFF in case incoming file are refused due to unknown or
          invalid record formats if you want to accept the file anyway
          (and, perhaps, postprocess it to fix its record format).

   SET CD HOME [ directory ]
          Specifies the target directory for the CD and KCD commands,
          when they are given without an argument, and also sets the
          value of the \v(home) variable.

   SET EXIT HANGUP { OFF, ON }
          Normally ON, meaning that when Kermit exits, it also explicitly
          hangs up the current SET LINE / SET PORT serial port according
          to the current SET MODEM TYPE and SET MODEM HANGUP METHOD, and
          closes the port device if it was opened by Kermit in the first
          place (as opposed to inherited). SET EXIT HANGUP OFF tells
          Kermit not to do this. This can't prevent the operating system
          from closing the device when Kermit exits (and it's a "last
          close") but if the port or modem have been conditioned to
          somehow ignore the close and keep the connection open, at least
          Kermit itself won't do anything explicit to hang it up or close
          it.

   SET FILE EOF { CTRL-Z, LENGTH }
          Specifies the end-of-file detection method to be used by
          C-Kermit when sending and receiving text files, and in the TYPE
          and similar text-file oriented commands. The normal and default
          method is LENGTH. You can specify CTRL-Z when handling CP/M or
          MS-DOS format text files, in which a Ctrl-Z (ASCII 26)
          character within the file marks the end of the file.

   SET FILE LISTSIZE number
          Allocates space for the given number of filenames to be filled
          in by the wildcard expander. The current number is shown by
          SHOW FILE. If you give a command that includes a filename
          containing a wildcard (such as "*") that matches more files
          that Kermit's list has room for, you can adjust the list size
          with this command.

   SET FILE STRINGSPACE number
          Allocates space for the given amount of filename strings for
          use by the wildcard expander. The current number is shown by
          SHOW FILE. The number is the total number of bytes of all the
          file specifications that match the given wildcard.

     If you need to process a bigger list of files than your computer
     has memory for, you might be able use an external file list. The
     Kermit SEND and the FTP PUT and GET commands accept a /LISTFILE:
     switch, which gives the name of a file that contains the list of
     files to be transferred. Example for UNIX:

  !find . -print | grep / > /tmp/names
  ftp put /update /recursive /listfile:/tmp/names

   SET LOCUS { AUTO, LOCAL, REMOTE }
          Added in C-Kermit 8.0.201.   Sets the locus for unprefixed file
          management commands such as CD, DIRECTORY, MKDIR, etc. When
          LOCUS is LOCAL these commands act locally and a REMOTE (or R)
          prefix (e.g. REMOTE CD, RCD, RDIR) is required to send file
          management commands to a remote server. When LOCUS is REMOTE,
          an L prefix is required to issue local file management commands
          (e.g. LCD, LDIR). The word LOCAL can't be used as a prefix
          since it is already used for declaring local variables. LOCUS
          applies to all types of connections, and thus is orthogonal to
          SET GET-PUT-REMOTE, which selects between Kermit and FTP for
          remote file-transfer and management commands. The default LOCUS
          is AUTO, which means we switch to REMOTE whenever an FTP
          connection is made, and to LOCAL whenever a non-FTP connection
          is made, and switch back accordingly whenever a connnection is
          closed. So by default, Kermit behaves in its traditional manner
          unless you make an FTP connection, in which case it acts like a
          regular FTP client (but better :-)   LOCUS applies to the
          following commands:

  Unprefixed    Remote       Local        Description        
   CD (CWD)      RCD          LCD          Change (Working) Directory
   CDUP          RCDUP        LCDUP        CD Up
   PWD           RPWD         LPWD         Print Working Directory
   DIRECTORY     RDIR         LDIR         Request a directory listinga
   DELETE        RDEL         LDEL         Delete (a) file(s)
   RENEME        RREN         LREN         Rename a file
   MKDIR         RMKDIR       LMKDIR       Create a directory
   RMDIR         RRMDIR       LRMDIR       Remove a directory

   SET MATCH { DOTIFILE, FIFO } { ON, OFF }
          Whether C-Kermit filename patterns (wildcards) should match
          filenames that start with dot (period), or (Unix only) FIFOs
          (named pipes). The defaults are to skip dotfiles in Unix but
          match them elsewhere, and to skip FIFOs. Applies to both
          interactive use and to server mode, when the server receives
          wildcards, e.g. in a GET command. Also see REMOTE SET MATCH.

   SET OPTIONS DIRECTORY /DOTFILES
          Now works for server listings too (UNIX only). Give this
          command prior to having Kermit enter server mode, and then it
          will show files whose names begin with dot (period) when sent a
          REMOTE DIRECTORY command.

   SET QUIET ON
          (as well as the -q command-line option) Now applies also to:

          + SET HOST connection progress messages.
          + "Press the X or E key to cancel" file-transfer message.
          + REMOTE CD response.
          + REMOTE LOGIN response.

   SET RECEIVE PERMISSIONS { ON, OFF }
          Tells C-Kermit whether to set the permissions of incoming files
          (received with Kermit protocol) from the permissions supplied
          in the file's Attribute packet (if any). Normally ON. Also see
          SET SEND PERMISSIONS.

   SET ROOT directory
          Like UNIX chroot, without requiring privilege. Sets the root
          for file access, does not allow reference to or creation of
          files outside the root, and can't be undone.

   SET SEND PERMISSIONS { ON, OFF }
          Tells C-Kermit whether to include file permissions in the
          attributes it includes with each file when sending with Kermit
          protocol. Also see SET RECEIVE PERMISSIONS.

   SET TCP { HTTP-PROXY, SOCKS-SERVER } /USER:name /PASSWORD:text
          These commands now allow specification of username and
          password.

   SET TERMINAL . . .
          (See [388]Section 12.)

   SET TRANSFER MESSAGE [ text ]
          Sets an initial text message to be displayed in the
          file-transfer display. The transfer message is automatically
          deleted once used, so must be set each time a message a
          desired. Any variables in the message are evaluated at the time
          the SET command is given. If the optional text is omitted, any
          transfer message that is currently set is removed. Synonym: SET
          XFER MSG. SHOW TRANSFER displays it if it has been set but not
          yet used.

   SHOW COMMUNICATIONS
          In C-Kermit 8.0, SHOW COMMUNICATIONS, when given in remote mode
          (i.e. before any connection has been established), tells the
          typical dialout device name for the particular platform on
          which it's running (e.g. TXA0: for VMS, or /dev/cua0p0 for
          HP-UX). On Unix platforms, it also tells the name of the
          lockfile directory. This way, you have an idea of what the SET
          LINE device name should look like, and if the SET LINE command
          fails, you know the name of the directory or device that is
          protected against you.

   SHOW VARIABLES [ name [ name [ ... ] ] ]
          In C-Kermit 8.0.201 you can request values of a list of
          built-in (\v(xxx)) variables. Each name is a pattern, as
          before, but now it a free pattern rather than an anchored one
          (explained in [389]Section 8.12) so now "show var date time"
          shows the values of all variables whose names include the
          strings "date" or "time".

   TAIL [ switches ] filename
          Equivalent to TYPE /TAIL [ other-switches ] filename.

   TRANSMIT /NOECHO [ other switches ] filename
          The /NOECHO switch is equivalent to giving the command SET
          TRANSMIT ECHO OFF prior to the TRANSMIT command, except the
          switch affects only the command with which it was given and
          does not affect the prevailing global setting.

   TRANSMIT /NOWAIT [ other switches ] filename
          The /NOWAIT switch is equivalent to giving the command SET
          TRANSMIT PROMPT 0 prior to the TRANSMIT command, except the
          switch affects only the command with which it was given and
          does not affect the prevailing global setting.

   TRANSMIT /NOWAIT /NOECHO /BINARY [ other switches ] filename
          When the TRANSMIT command is given with the /NOWAIT, /NOECHO,
          and /BINARY switches, this activates a special "blast the whole
          file out the communications connection all at once" mode that
          Kermit didn't have prior to version 8.0. There has been
          increasing demand for this type of transmission with the advent
          of devices that expect image (e.g. .JPG) or sound (e.g. .MP3)
          files as raw input. The obvious question is: how does the
          receiving device know when it has the whole file? This depends
          on the device, of course; usually after a certain amount of
          time elapses with nothing arriving, or else when Kermit hangs
          up or closes the connection.

   TYPE /CHARACTER-SET:name
          Allows you to specify the character set in which the file to be
          typed is encoded.

   TYPE /NUMBER
          Adds line numbers.

   TYPE /OUTPUT:filename
          Sends the results of the TYPE command to the given file.

   TYPE /TRANSLATE-TO:name
          Used in conjunction with TYPE /CHARACTER-SET:xxx; allows you to
          specify the character set in which the file is to be displayed.

   TYPE /TRANSPARENT
          Used to disable character-set translation in the TYPE command,
          which otherwise can take place automatically based on file
          scanning, even when /CHARACTER-SET and /TRANSLATE-TO switches
          are not given.

   VOID text
          Parses the text, evaluating any backslash items in it (such as
          function calls) but doesn't do anything further, except
          possibly printing error messages. Useful for invoking functions
          that have side effects without using or printing their direct
          results, e.g. "void \fsplit(\%a,&a)".

  Symbolic Links in UNIX

   The UNIX versions of C-Kermit have had /FOLLOWLINKS and /NOFOLLOWLINKS
   switches added to several commands to control the treatment of
   symbolic links. Different commands deal differently with symbolic
   links:

   Kermit SEND, FTP MPUT
          /NOFOLLOWLINKS is the default, which means symbolic links are
          skipped entirely. The alternative, /FOLLOWLINKS, should be used
          with caution, since an innocent link might point to a whole
          file system, or it might cause a loop. There is no way in
          Kermit or FTP protocol to send the link itself. We either skip
          them or follow them; we can't duplicate them.

   DIRECTORY
          /NOFOLLOWLINKS is the default, which means the DIRECTORY
          command lists symbolic links in a way that shows they are
          links, but it does not follow them. The alternative,
          /FOLLOWLINKS, follows links and gives information about the
          linked-to directories and files.

   DELETE, RMDIR
          The DELETE command does not have link-specific switches. DELETE
          never follows links. If you tell Kermit to delete a symbolic
          link, it deletes the link itself, not the linked-to file. Ditto
          for RMDIR.

   COPY
          The COPY command behaves just like the UNIX cp command; it
          always follows links.

   RENAME
          The RENAME command behaves just like the UNIX mv command; it
          operates on links directly rather than following.

   [ [390]Top ] [ [391]Contents ] [ [392]C-Kermit Home ] [ [393]Kermit
   Home ]
  __________________________________________________________________________

8. OTHER SCRIPTING IMPROVEMENTS

  8.1. Performance and Debugging

   A command cache for frequently used commands plus some related
   optimizations increases the speed of compute-bound scripts by anywhere
   from 50% to 1000%.

   The new PROMPT command can be used to set breakpoints for debugging
   scripts. If executed in a command file or macro, it gives you an
   interactive command prompt in the current context of the script, with
   all its variables, arguments, command stack, etc, available for
   examination or change, and the ability to resume the script at any
   point (END resumes it, Ctrl-C or STOP cancels it and returns to top
   level).

   The new Ctrl-C trapping feature ([394]Section 8.14) lets you intercept
   interruption of scripts. This can be used in combination with the
   PROMPT command to debug scripts. Example:

define ON_CTRLC {
    echo INTERRUPTED BY CTRL-C...
    echo The command stack has not yet been rolled back:
    show stack
    echo Type Ctrl-C again or use the END command to return to top level.
    prompt Debug>
}

   Adding this ON_CTRL definition to your script lets you interrupt it at
   any point and get prompt that is issued at the current command level,
   so you can query local variables, etc.

   [ [395]Top ] [ [396]Contents ] [ [397]C-Kermit Home ] [ [398]Kermit
   Home ]
     _________________________________________________________________

  8.2. Using Macros as Numeric Variables

   A macro is a way to assign a value to a name, and then use the name to
   refer to the value. Macros are used in two ways in Kermit: as
   "subroutines" or functions composed of Kermit commands, which are
   executed, or as variables to hold arbitrary values -- text, numbers,
   filenames, etc.

   When a macro is to be executed, its name is given as if it were a
   C-Kermit command, optionally preceded by the word "do". When a macro
   is used as a variable, it must be "escaped" with \m(xxx) (or
   equivalent function, e.g. \s(xxx), \:(xxx), \fdefinition(xxx)), where
   xxx is the macro name, for example:

  define filename /usr/olga/oofa.txt
  send \m(filename)

   Of course variables can also hold numbers:

  define size 17
  declare \&a[\m(size)]
  ...
  define index 3
  if ( == \m(index) 3 ) echo The third value is: \&a[\m(index)]
  evaluate index (\m(index) * 4)
  if ( > \m(index) \m(size) ) echo Out of range!

   But these are contexts in which only numbers are valid. C-Kermit 8.0
   has been changed to treat non-escaped non-numeric items in strictly
   numeric contexts as macro names. So it is now possible (but not
   required) to omit the \m(...) notation and just use the macro name in
   these contexts:

  define size 17
  declare \&a[size]
  ...
  define index 3
  if ( == index 3 ) echo The third value is: \&a[index]
  evaluate index (index * 4)
  if ( > index size ) echo Out of range!

   This is especially nice for loops that deal with arrays. Here, for
   example, is a loop that reverses the order of the elements in an
   array. Whereas formerly it was necessary to write:

  .\%n ::= \fdim(&a)
  for \%i 1 \%n/2 1 {
      .tmp := \&a[\%n-\%i+1]
      .\&a[\%n-\%i+1] := \&a[\%i]
      .\&a[\%i] := \m(tmp)
  }

   Recoding this to use macro names "i" and "n" instead of the backslash
   variables \%i and \%n, we have:

  .n ::= \fdim(&a)
  for i 1 n/2 1 {
      .tmp := \&a[n-i+1]
      .\&a[n-i+1] := \&a[i]
      .\&a[i] := \m(tmp)
  }

   which reduces the backslash count to less than half. The final
   statement in the loop could be written ".\&a[i] ::= tmp" if the array
   contained only numbers (since ::= indicates arithmetic expression
   evaluation).

   Also, now you can use floating-point numbers in integer contexts (such
   as array subscripts), in which case they are truncated to an integer
   value (i.e. the fractional part is discarded).

   Examples of numeric contexts include:

     * Array subscripts.
     * Any numeric function argument.
     * Right-hand side of ::= assignments.
     * EVALUATE command or \fevaluate() function expression.
     * The INCREMENT or DECREMENT by-value.
     * IF =, >, <, !=, >=, and <= comparands.
     * The IF number construct.
     * FOR-loop variables.
     * STOP, END, and EXIT status codes.
     * The INPUT timeout value.
     * PAUSE, WAIT, SLEEP, MSLEEP intervals.
     * The SHIFT argument.
     * Numeric switch arguments, e.g. TYPE /WIDTH:number, SEND
       /LARGER:number.
     * SCREEN MOVE-TO row and column number.
     * Various SET DIAL parameters (timeout, retry limit, etc).
     * Various SET SEND or RECEIVE parameters (packet length, window
       size, etc).
     * Various other SET parameters.

   and:

     * S-Expressions (explained in [399]Section 9).

   Macro names used in numeric contexts must not include mathematical
   operators. Although it is legal to create a macro called "foo+bar", in
   a numeric context this would be taken as the sum of the values of
   "foo" and "bar". Any such conflict can be avoided, of course, by
   enclosing the macro name in \m(...).

   [ [400]Top ] [ [401]Contents ] [ [402]C-Kermit Home ] [ [403]Kermit
   Home ]
     _________________________________________________________________

  8.3. New IF Conditions

   Several new IF conditions are available:

   IF DECLARED arrayname
          Explained in [404]Section 8.6.

   IF KBHIT
          Allows a script to test whether a key was pressed without
          actually trying to read it.

   IF KERBANG (Unix only)
          True if Kermit was started from a Kerbang script. This is
          useful for knowing how to interpret the \&@[] and \&_[]
          argument vector arrays, and under what conditions to exit.

   IF INTEGER n
          This is just a synonym for IF NUMERIC, which is true if n
          contains only digits (or, if n is a variable, its value
          contains only digits).

   By contrast, IF FLOAT n succeeds if n is a floating-point number OR an
   integer (or a variable with floating-point or integer value).
   Therefore, IF FLOAT should be used whenever any kind of number is
   acceptable, whereas IF INTEGER (or IF NUMERIC) when only an integer
   can be used.

   [ [405]Top ] [ [406]Contents ] [ [407]C-Kermit Home ] [ [408]Kermit
   Home ]
     _________________________________________________________________

  8.4. The ON_UNKNOWN_COMMAND Macro

   The new ON_UNKNOWN_COMMAND macro, if defined, is executed whenever you
   give a command that is not known to C-Kermit; any operands are passed
   as arguments. Here are some sample definitions:

  DEF ON_UNKNOWN_COMMAND telnet \%1 ; Treat unknown commands as hostnames
  DEF ON_UNKNOWN_COMMAND dial \%1   ; Treat unknown commands phone numbers
  DEF ON_UNKNOWN_COMMAND take \%1   ; Treat unknown commands as filenames
  DEF ON_UNKNOWN_COMMAND !\%*       ; Treat unknown commands as shell commands

   The ON_CD macro, if defined, is executed whenever Kermit is given a CD
   (change directory) command (8.0.211). Upon entry to this macro, the
   directory has already changed and the new directory string is
   available in the \v(directory) variable, and also as the first
   argument (\%1).

   [ [409]Top ] [ [410]Contents ] [ [411]C-Kermit Home ] [ [412]Kermit
   Home ]
     _________________________________________________________________

  8.5. The SHOW MACRO Command

   The SHOW MACRO command has been changed to accept more than one macro
   name:

  (setq a 1 b 2 c 3)
  show mac a b c
  a = 1
  b = 2
  c = 3

   An exact match is required for each name (except that case doesn't
   matter). If you include wildcard characters, however, a pattern match
   is performed:

  show mac [a-c]*x

   shows all macros whose names start with a, b, or c, and end with x.

   [ [413]Top ] [ [414]Contents ] [ [415]C-Kermit Home ] [ [416]Kermit
   Home ]
     _________________________________________________________________

  8.6. Arrays

   A clarification regarding references to array names (as opposed to
   array elements): You can use array-name "abbreviations" like &a only
   in contexts that expect array names, like ARRAY commands or array-name
   function arguments such as the second argument of \fsplit(). In a
   LOCAL statement, however, you have to write \&a[], since "local &a"
   might refer to a macro named "&a".

   In function arguments, however, you MUST use the abbreviated form:
   \fsplit(\%a,&a) or \fsplit(\%a,&a[]). If you include the backslash (as
   in "\fsplit(\%a,\&a[])") a parse error occurs.

   Here are the new array-related commands:

   IF DECLARED arrayname
          Allows a script to test whether an array has been declared. The
          arrayname can be a non-array backslash variable such as \%1 or
          \m(name), in which case it is evaluated first, and the result
          is treated as the array name. Otherwise, arrayname is treated
          as in the ARRAY commands: it can be a, &a, &a[], \&a, \&a[],
          \&a[3], \&a[3:9], etc, with the appropriate results in each
          case. Synonym: IF DCL.

   UNDECLARE arrayname
          UNDECLARE is a new top-level command to undeclare an array.
          Previously this could only be done with "declare \&a[0]" (i.e.
          re-declare the array with a dimension of 0).

   ARRAY LINK linkname arrayname
          Creates a symbolic link from the array named by linkname (which
          must be the name of an array that is not yet declared in the
          current context) to the array named by arrayname (which must
          the name of a currently declared array that is not itself a
          link, or a variable containing the name of such an array). The
          two names indicate the same array: if you change an array
          element, the change is reflected in the link too, and vice
          versa. If you undeclare the link, the real array is unaffected.
          If you undeclare the real array, all links to it disappear. If
          you resize an array (directly or through a link), all links to
          it are updated automatically.

   Array links let you pass array names as arguments to macros. For
   example, suppose you had a program that needed to uppercase all the
   elements of different arrays at different times. You could write a
   macro to do this, with the array name as an argument. But without
   array links, there would be no way to refer to the argument array
   within the macro. Array links make it easy:

  define arrayupper {
      local \&e[] \%i
      array link \&e[] \%1
      for i 1 \fdim(&e) 1 { .\&e[i] := \fupper(\&e[i]) }
  }
  declare \&a[] = these are some words
  arrayupper &a
  show array &a

   The macro declares the array link LOCAL, which means it doesn't
   conflict with any array of the same name that might exist outside the
   macro, and that the link is destroyed automatically when the macro
   exits. This works, by the way, even if the link name and the macro
   argument name are the same, as long as the link is declared LOCAL.

   As noted, you can't make a link to a nonexistent array. So when
   writing a macro whose job is to create an array whose name is passed
   as an argument, you must declare the array first (the size doesn't
   matter as long as it's greater than 0). Example:

  define tryme {                ; Demonstration macro
      local \&e[]               ; We only need this inside the macro
      array link \&e[] \%1      ; Make local link
      shift                     ; Shift argument list
      void \fsplit(\%*,&e)      ; Split remainder of arg list into array
  }
  declare \&a[1]                ; Declare target array in advance
  tryme &a here are some words  ; Invoke the macro with array name and words
  show array a                  ; See the results

   One final improvement allows the macro itself to declare the array
   (this was not possible in earlier Kermit releases): if the array name
   in the DECLARE command is a variable (and not an array name), or
   includes variables, the resulting value is used as the array name. So:

  define tryme {                ; Demonstration macro
      declare \%1[1]            ; Preliminary declaration for target array
      local \&e[]               ; We only need this inside the macro
      array link \&e[] \%1      ; Make local link
      shift                     ; Shift argument list
      void \fsplit(\%*,&e)      ; Split remainder of arg list into array
  }
  tryme &a here are some words  ; Invoke the macro with array name and words
  show array a                  ; See the results

   The SHOW ARRAY command now indicates whether an array name is a link.

   Also see the descriptions of [417]\fjoin() and [418]\fsplit(), plus
   [419]Section 8.10 on the MINPUT command, which shows how an entire
   array (or segment of it) can be used as the MINPUT target list.

   [ [420]Top ] [ [421]Contents ] [ [422]C-Kermit Home ] [ [423]Kermit
   Home ]
     _________________________________________________________________

  8.7. New or Improved Built-in Variables and Functions

   The following new built-in variables are available:

  \v(buildid)       A date string like "20000808" indicating when C-Kermit was
built.
  \v(ftime)         Current time, secs since midnight, including fraction of se
cond.
  \v(iprompt)       The current SET PROMPT value
  \v(sexp)          The most recent S-Expression (see [424]Section 9)
  \v(sdepth)        The current S-Expression invocation depth ([425]Section 9)
  \v(svalue)        The value of the most recent S-Expression ([426]Section 9)

  \v(ftp_code)      Most recent FTP response code ([427]Section 3)
  \v(ftp_connected) FTP connection status ([428]Section 3)
  \v(ftp_cpl)       FTP Command Protection Level ([429]Section 3.2)
  \v(ftp_dpl)       FTP Data Protection Level ([430]Section 3.2)
  \v(ftp_getputremote) The current SET GET-PUT-REMOTE setting ([431]Section 3.8
)
  \v(ftp_host)      Name or IP address of FTP server ([432]Section 3)
  \v(ftp_loggedin)  FTP login status ([433]Section 3)
  \v(ftp_message)   Most recent FTP response message ([434]Section 3)
  \v(ftp_security)  FTP Security method ([435]Section 3.2)
  \v(ftp_server)    OS type of FTP server ([436]Section 3)

  \v(http_code)       Most recent HTTP response code
  \v(http_connected)  HTTP connection status
  \v(http_host)       Name or IP address of HTTP server
  \v(http_message)    Most recent HTTP response message
  \v(http_security)   TLS cipher used to secure the HTTP session

  \v(hour)            Hour of the day, 0 to 23.
  \v(timestamp)       Equivalent to "\v(ndate) \v(time)".

  \v(log_debug)       Current debug log file, if any.
  \v(log_packet)      Current packet log file, if any.
  \v(log_session)     Current session log file, if any.
  \v(log_transaction) Current transaction log file, if any.
  \v(log_connection)  Current connection log file, if any.

   The following new or improved built-in functions are available:

  \fcmdstack()            Allows programmatic access to the command stack.
  \fcvtdate()             [437]Section 8.13, format options added
  \fdelta2secs()          [438]Section 8.13
  \fdostounixpath(s1)     Converts a DOS filename to Unix format.
  \fsplit()               Now allows grouping/nesting in source string.
  \fword()                Allows the same grouping and nesting.
  \fjoin(&a,s1,n1,n2)     Copies an array into a single string.
  \fsubstitute(s1,s2,s3)  Substitutes characters within a string.
  \freplace()             Has new 4th "occurrence" argument.
  \fsexpression()         Evaluates an S-Expression (explained in [439]Section
9).
  \ftrim(), \fltrim()     Now trim CR and LF by default, as well as SP and Tab.
  \funixtodospath(s1)     Converts a Unix filename to DOS format.
  \fkeywordval(s1,c1)     Assigns values to keywords (macros) (explained below)
.

   Most functions that have "2" in their names to stand for the word "to"
   can now also be written with "to", e.g. "\fdelta2secs(),"
   \fdeltatosecs()."

   \funtabify(string)
          (New to 8.0.211) Replaces Horizontal Tab characters in the
          given string with spaces based on VT100-like tab stops.

   \fverify(s1,s2,n)
          As of version 8.0.211, returns -1 if s2 is an empty string.
          Previously it returned 0, making \fverify(abc,\%a) look as if
          \%a was a string combosed of a's, b's, and/or c's when in fact
          it contained nothing.

   \fcode(string)
          As of version 8.0.211, returns 0 if string is empty or missing.
          Previously it returned the empty string, which made it unsafe
          to use in arithmetic or boolean expressions.

   \v(inscale)
          New to version 8.0.211, its value is the INPUT SCALE-FACTOR
          ([440]Section 8.10), default 1.0.

  8.7.1. The \fkeywordval() Function

   \fkeywordval(s1,c1) is new to C-Kermit 8.0. Given a string s1 of the
   form "name=value", it creates a macro with the given name and assigns
   it the given value. If no value appears after the equal sign, any
   existing macro of the given name is undefined. Blanks are
   automatically trimmed from around the name and value. The optional c1
   parameter is the assignment operator character, equal sign (=) by
   default. This function is handy for processing keyword parameters or
   any other form of parameter-value pair. Suppose, for example, you want
   to write a macro that accepts keyword parameters rather than
   positional ones:

  define MYDIAL {
      local \%i modem hangup method device speed number
      def number 5551234          ; Assign default parameter values
      def speed 57600
      def modem usrobotics
      def hangup rs232
      def method tone
      def country 1
      for \%i 1 \v(argc)-1 1 {    ; Parse any keyword parameters...
          if not \fkeywordval(\&_[\%i]) end 1 Bad parameter: "\&_[\%i]"
      }
      set dial country \m(country)
      set modem type \m(modem)
      set modem hang \m(hangup)
      set dial method \m(tone)
      set line \m(device)
      if fail stop 1
      set speed \m(speed)
      if fail stop 1
      show comm
      set dial display on
      dial \m(number)
      if success connect
  }

   In this example, all the defaults are set up inside the macro, and
   therefore it can be invoked with no parameters at all. But if you want
   to have the macro dial a different number, you can supply it as
   follows:

  mydial number=7654321

   You can supply any number of keyword parameters, and you can give them
   in any order:

  mydial number=7654321 hangup=modem speed=115200

  8.7.2. The \fsplit(), \fjoin(), and \fword() Functions

   \fjoin(&a,s1,n1,n2) is also new; it creates a string from an array (or
   a piece of one). &a is the name of the array (a range specifier can be
   included); s1 is a character or string to separate each element in the
   result string (can be omitted, in which case the elements are not
   separated at all), and n1 is a grouping mask, explained below. If s1
   is empty or not specified, the array elements are separated with
   spaces. If you want the elements concatenated with no separator,
   include a nonzero n2 argument. Given the array:

  declare \&a[] = 0 1 2 3 4 5 6 7 8 9

   you can get effects like this:

  \fjoin(&a)      0 1 2 3 4 5 6 7 8 9
  \fjoin(&a,:)    0:1:2:3:4:5:6:7:8:9
  \fjoin(&a,{,})  0,1,2,3,4,5,6,7,8,9
  \fjoin(&a,...)  0...1...2...3...4...5...6...7...8...9
  \fjoin(&a,,,1)  0123456789

   \fsplit(), \fword(), \fstripb(), and \fjoin() accept a "grouping mask"
   argument, n1, which is a number from 0 to 63, in which:

   1 = "" doublequotes
   2 = {} braces
   4 = '' singlequotes
   8 = () parentheses
  16 = [] square brackets
  32 = <> angle brackets

   These can be OR'd (added) together to make any number 0-63 (-1 is
   treated the same as 63, 0 means no grouping). If a bit is on, the
   corresponding kind of grouping is selected. (If more than 1 bit is set
   for \fjoin(), only the lowest-order one is used.)

   If you include the same character in the grouping mask and the include
   list, the grouping mask takes precedence. Example:

  def \%a  a "b c d" e
  \fsplit(\%a,&a[],,,-1)  = 3  <-- doublequote used for grouping
  \fsplit(\%a,&a[],,",-1) = 3  <-- doublequote still used for grouping

   Nesting of matched left and right grouping characters (parentheses,
   braces, and brackets, but not quotes) is recognized. Example:

  def \%a a (b c <d e [f g {h i} j k] l m> n o) p
  \fsplit(\%a,&a,,,0)  = 16 (no grouping)
  \fsplit(\%a,&a,,,2)  = 15 (braces only)
  \fsplit(\%a,&a,,,16) = 11 (square brackets only)
  \fsplit(\%a,&a,,,32) =  7 (angle brackets only)
  \fsplit(\%a,&a,,,63) =  3 (all)
  \fsplit(\%a,&a,,,-1) =  3 (all)

   \fsplit() and \fjoin() are "reciprocal" functions. You can split a
   string up into an array and join it back into a new string that is
   equivalent, as long as \fsplit() and \fjoin() are given equivalent
   grouping masks, except that the type of braces might change. Example:

  def \%a a {b c [d e] f g} "h i" j <k l> m
  echo STRING=[\%a]
  echo WORDS=\fsplit(\%a,&a,,,-1)
  show array a
  asg \%b \fjoin(&a,{ },2)
  echo JOIN  =[\%b]
  echo WORDS=\fsplit(\%b,&b,,,-1)
  show array b

   The arrays a and b are identical. The strings a and b are as follows:

  \%a: a {b c [d e] f g} "h i" j <k l> m
  \%b: a {b c [d e] f g} {h i} j {k l} m

   It is possible to quote separator grouping characters with backslash
   to override their grouping function. And of course to include
   backslash itself in the string, it must be quoted too. Furthermore,
   each backslash must be doubled, so the command parser will still pass
   one backslash to \fsplit() for each two that it sees. Here are some
   examples using \fsplit() with a grouping mask of 8 (treat parentheses
   as grouping characters).

  String                  Result
    a b c d e f             6
    a b\\ c d e f           5
    a b (c d e) f           4
    a b \\(c d e\\) f       6
    a b \\\\(c d e\\\\) f   7

   \fsplit() has also been changed to create its array (if one is given)
   each time it is called, so now it can be conveniently called in a loop
   without having to redeclare the array each time.

   Incidentally... Sometimes you might want to invoke \fsplit() in a
   situation where you don't care about its return value, e.g. when you
   just want to fill the array. Now you can "call" \fsplit() or any other
   function with the new [441]VOID command:

  void \fsplit(\%a,&a)

   \fsplit() and \fjoin() also accept a new, optional 6th argument, an
   options flag, a number that can specify a number of options. So far
   there is just one option, whose value is 1:

   separator-flag
          Normally separators are collapsed. So, for example,

  \fword(Three        little          words,2)

          returns "little" (the second word). Space is a separator, but
          there are multiple spaces between each word. If the value 1 is
          included in the option flag, however, each separator counts. If
          two separators are adjacent, an empty word is produced between
          them. This is useful for parsing (e.g.) comma-separated lists
          exported from databases or spreadsheets.

  8.7.3. The \fcmdstack() Function

   The new \fcmdstack() function gives access to the command stack:

   \fcmdstack(n1,n2)
          Arguments: n1 is the command stack level. If omitted, the
          current level, \v(cmdlevel), is used. n2 is a function code
          specifying the desired type of information:

  0 (default) = name of object at level n1.
  1 (nonzero) = object type (0 = prompt; 1 = command file; 2 = macro).

          The default for n2 is 0.

   The name associated with prompt is "(prompt)". Here's a loop that can
   be included in a macro or command file to show the stack (similar to
   what the SHOW STACK command does):

  for \%i \v(cmdlevel) 0 -1 {
      echo \%i. [\fcmdstack(\%i,1)] \fcmdstack(\%i,0)
  }

   In this connection, note that \v(cmdfile) always indicates the most
   recently invoked active command file (if any), even if that file is
   executing a macro. Similarly, \v(macro) indicates the most recently
   invoked macro (if any), even if the current command source is not a
   macro. The name of the "caller" of the currently executing object
   (command file or macro) is:

  \fcmdstack(\v(cmdlevel)-1)

   and its type is:

  \fcmdstack(\v(cmdlevel)-1,1)

   To find the name of the macro that invoked the currently executing
   object, even if one or more intermediate command files (or prompting
   levels) are involved, use a loop like this:

  for \%i \v(cmdlevel)-1 0 -1 {
      if = \fcmdstack(\%i,1) 2 echo CALLER = \fcmdstack(\%i,0)
  }

   Of course if you make a macro to do this, the macro must account for
   its own additional level:

  define CALLER {
      for \%i \v(cmdlevel)-2 0 -1 {
          if = \fcmdstack(\%i,1) 2 return \fcmdstack(\%i,0)
      }
      return "(none)"
  }

   The built-in variable \v(cmdsource) gives the current command source
   as a word ("prompt", "file", or "macro").

  8.7.4. The VOID Command

   VOID is like ECHO in that all functions and variables in its argument
   text are evaluated. but it doesn't print anything (except possibly an
   error message if a function was invocation contained or resulted in
   any errors). VOID sets FAILURE if it encounters any errors, SUCCESS
   otherwise.

   [ [442]Top ] [ [443]Contents ] [ [444]C-Kermit Home ] [ [445]Kermit
   Home ]
     _________________________________________________________________

  8.8. The RETURN and END Commands

   The execution of a macro is terminated in any of the following ways:

     * With an END [ number [ message ] ] command. If a number is given,
       the macro succeeds if the number is 0, and fails if it is not
       zero; if a number is not given, the macro succeeds.
     * With a STOP command, which works just like END except it peels
       back the command stack all the way to top level.
     * With a RETURN [ text ] command, in which case the macro always
       succeeds.
     * By running out of commands to execute, in which case the macro
       succeeds or fails according the most recently executed command
       that sets success or failure.

   The same considerations apply to command files invoked by the TAKE
   command.

   If a macro does not execute any commands that set success or failure,
   then invoking the macro does not change the current SUCCESS/FAILURE
   status. It follows, then, that the mere invocation of a macro does not
   change the SUCCESS/FAILURE status either. This makes it possible to
   write macros to react to the status of other commands (or macros), for
   example:

  define CHKLINE {
      if success end 0
      stop 1 SET LINE failed - please try another device.
  }
  set modem type usrobotics
  set line /dev/cua0
  chkline
  set speed 57600
  dial 7654321

   By the way, none of this is news. But it was not explicitly documented
   before, and C-Kermit 7.0 and earlier did not always handle the RETURN
   statement as it should have.

   [ [446]Top ] [ [447]Contents ] [ [448]C-Kermit Home ] [ [449]Kermit
   Home ]
     _________________________________________________________________

  8.9. UNDEFINing Groups of Variables

   The UNDEFINE command, which previously accepted one variable name, now
   accepts a list of them, and also accepts wildcard notation to allow
   deletion of variables that match a given pattern.

   UNDEFINE [ switches ] name [ name [ name [ ... ] ] ]
          Undefines the variables whose names are given. Up to 64 names
          may be given in one UNDEFINE command.

   If you omit the switches and include only one name, the UNDEFINE
   command works as before.

   Switches include:

   /MATCHING
          Specifies that the names given are to treated as patterns
          rather than literal variable names. Note: pattern matching
          can't be used with array references; use the ARRAY command to
          manipulate arrays and subarrays.

   /LIST
          List the name of each variable to be undefined, and whether it
          was undefined successfully ("ok" or "error"), plus a summary
          count at the end.

   /SIMULATE
          List the names of the variables that would be deleted without
          actually deleting them. Implies /LIST.

   The UNDEFINE command fails if there were any errors and succeeds
   otherwise.

   The new _UNDEFINE command is like UNDEFINE, except the names are
   assumed to be variable names themselves, which contain the names (or
   parts of them) of the variables to be undefined. For example, if you
   have the following definitions:

  define \%a foo
  define foo This is some text

   then:

  undef \%a

   undefines the variable \%a, but:

  _undef \%a

   undefines the macro foo.

   Normal Kermit patterns are used for matching; metacharacters include
   asterisk, question mark, braces, and square brackets. Thus, when using
   the /MATCHING switch, if the names of the macros you want to undefine
   contain any of these characters, you must quote them with backslash to
   force them to be taken literally. Also note that \%* is not the name
   of a variable; it is a special notation used within a macro for "all
   my arguments". The command "undef /match \%*" deletes all \%x
   variables, where x is 0..9 and a..z. Use "undef /match \%[0-9]" to
   delete macro argument variables or "undef /match \%[i-n]" to delete a
   range of \%x variables.

   [ [450]Top ] [ [451]Contents ] [ [452]C-Kermit Home ] [ [453]Kermit
   Home ]
     _________________________________________________________________

  8.10. The INPUT and MINPUT Commands

   As of C-Kermit 8.0.211, the INPUT and MINPUT commands accept a switch:

   [M]INPUT /NOMATCH timeout
          The /NOMATCH switch allows INPUT or MINPUT to read incoming
          material for the specified amount of time, without attempting
          to match it with any text or patterns. When this switch is
          included, the [M]INPUT command succeeds when the timeout
          interval expires, with \v(instatus) set to 1, meaning "timed
          out", or fails upon interruption or i/o error.

   Also in version 8.0.211, there is a new way to apply a scale factor to
   [M]INPUT timeouts:

   SET INPUT SCALE-FACTOR floating-point-number
          This scales all [M]INPUT timeouts by the given factor, allowing
          time-sensitive scripts to be adjusted to changing conditions
          such as congested networks or different-speed modems without
          having to change each INPUT-class command. This affects only
          those timeouts that are given in seconds, not as wall-clock
          times. Although the scale factor can have a fractional part,
          the INPUT timeout is still an integer. The new built-in
          variable \v(inscale) tells the current INPUT SCALE-FACTOR.

   The MINPUT command can be used to search the incoming data stream for
   several targets simultaneously. For example:

  MINPUT 8 one two three

   waits up to 8 seconds for one of the words "one", "two", or "three" to
   arrive. Words can be grouped to indicate targets that contain spaces:

  MINPUT 8 nineteeen twenty "twenty one"

   And of course you can also use variables in place of (or as part of)
   the target names:

  MINPUT 8 \%a \&x[3] \m(foo)

   Until now you had to know the number of targets in advance when
   writing the MINPUT statement. Each of the examples above has exactly
   three targets.

   But suppose your script needs to look for a variable number of
   targets. For this you can use arrays and \fjoin(), described in
   [454]Section 8.7. Any number of \fjoin() invocations can be included
   in the MINPUT target list, and each one is expanded into the
   appropriate number of separate targets each time the MINPUT command is
   executed. Example:

  declare \&a[10] = one two three
  minput 10 foo \fjoin(&a) bar

   This declares an array of ten elements, and assigns values to the
   first three of them. The MINPUT command looks for these three (as well
   as the words "foo" and "bar"). Later, if you assign additional
   elements to the array, the same MINPUT command also looks for the new
   elements.

   If an array element contains spaces, each word becomes a separate
   target. To create one target per array element, use \fjoin()'s
   grouping feature:

  dcl \&a[] = {aaa bbb} {ccc ddd} {xxx yyy zzz}

  minput 10 \fjoin(&a)     <-- 7 targets
  minput 10 \fjoin(&a,,2)  <-- 3 targets

   [ [455]Top ] [ [456]Contents ] [ [457]C-Kermit Home ] [ [458]Kermit
   Home ]
     _________________________________________________________________

  8.11. Learned Scripts

   C-Kermit now includes a simple script recorder that monitors your
   commands, plus your actions during CONNECT mode, and automatically
   generates a script program that mimics what it observed. You should
   think of this feature as a script-writing ASSISTANT since, as you will
   see [459]later in this section, the result generally needs some
   editing to make it both secure and flexible. The script recorder is
   controlled by the new LEARN command:

   LEARN [ /ON /OFF /CLOSE ] [ filename ]
          If you give a filename, the file is opened for subsequent
          recording. The /ON switch enables recording to the current file
          (if any); /OFF disables recording. /CLOSE closes the current
          script recording file (if any). If you give a filename without
          any switches, /ON is assumed.

   The /OFF and /ON switches let you turn recording off and on during a
   session without closing the file.

   When recording:

     * All commands that you type (or recall) at the prompt are recorded
       in the file except:
          + LEARN commands are not recorded.
          + The CONNECT command is not recorded.
          + The TELNET command is converted to SET HOST /NETWORK:TCP.
     * Commands obtained from macros or command files are not recorded.
     * During CONNECT:
          + Every line you type is converted to an OUTPUT command.
          + The last prompt before any line you type becomes an INPUT
            command.
          + Timeouts are calculated automatically for each INPUT command.
          + A PAUSE command is inserted before each OUTPUT command just
            to be safe.

   Thus the script recorder is inherently line-oriented. It can't be used
   to script character-oriented interactions like typing Space to a
   "More?" prompt or editing a text file with VI or EMACS.

   But it has advantages too; for example it takes control characters
   into account that might not be visible to you otherwise, and it
   automatically converts control characters in both the input and output
   streams to the appropriate notation. It can tell, for example that the
   "$ " prompt on the left margin in UNIX is really {\{13}\{10}$ },
   whereas in VMS it might be {\{13}\{10}\{13}$ }. These sequences are
   detected and recorded automatically.

   A learned script should execute correctly when you give a TAKE command
   for it. However, it is usually appropriate to edit the script a bit.
   The most important change would be to remove any passwords from it.
   For example, if the script contains:

  INPUT 9 {\{13}\{10}Password: }
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT bigsecret\{13}

   you should replace this by something like:

  INPUT 9 {\{13}\{10}Password: }
  IF FAIL STOP 1 INPUT timeout
  ASKQ pswd Please type your password:
  PAUSE 1
  OUTPUT \m(pswd)\{13}

   The LEARN command can't do this for you since it knows nothing about
   "content"; it only knows about lines and can't be expected to parse or
   understand them -- after all, the Password prompt might be in some
   other language. So remember: if you use the LEARN command to record a
   login script, be sure edit the resulting file to remove any passwords.
   Also be sure to delete any backup copies your editor or OS might have
   made of the file.

   Other manual adjustments might also be appropriate:

     * If the target of an INPUT command can vary, you can replace the
       INPUT command with MINPUT and the appropriate target list, and/or
       the target with a \fpattern(). For example, suppose you are
       dialing a number that can be answered by any one of 100 terminal
       servers, whose prompts are ts-00>, ts-01>, ts-02>, ... ts-99>. The
       script records a particular one of these, but you want it to work
       for all of them, so change (e.g.):
  INPUT 10 ts-23>  ; or whatever
       to:
  INPUT 10 \fpattern(ts-[0-9][0-9]>)
     * The INPUT timeout values are conservative, but they are based only
       on a single observation; you might need to tune them.
     * The PAUSE commands might not be necessary, or the PAUSE interval
       might need adjustment.
     * In case you made typographical errors during recording, they are
       incorporated in your script; you can edit them out if you want to.

   Here is a sample script generated by Kermit ("learn vms.ksc") in which
   a Telnet connection is made to a VMS computer, the user logs in,
   starts Kermit on VMS, sends it a file, and then logs out:

  ; Scriptfile: vms.ksc
  ; Directory:  /usr/olga
  ; Recorded:   20001124 15:21:23

  SET HOST /NETWORK:TCP vms.xyzcorp.com
  IF FAIL STOP 1 Connection failed

  INPUT 7 {\{13}\{10}\{13}Username: }
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT olga\{13}
  INPUT 3 {\{13}\{10}\{13}Password: }
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT secret\{13}
  INPUT 18 {\{13}\{10}\{13}$ }
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT set default [.incoming]\{13}
  INPUT 12 {\{13}\{10}\{13}$ }
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT kermit\{13}
  INPUT 15 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>}
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT receive\{13}
  send myfile.txt

  INPUT 18 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>}
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT exit\{13}
  INPUT 6 {\{13}\{10}\{13}$ }
  IF FAIL STOP 1 INPUT timeout
  PAUSE 1
  OUTPUT logout\{13}
  close
  exit

   The commands generated by Kermit during CONNECT (INPUT, IF FAIL,
   PAUSE, and OUTPUT) have uppercase keywords; the commands typed by the
   user are in whatever form the user typed them (in this case,
   lowercase).

   [ [460]Top ] [ [461]Contents ] [ [462]C-Kermit Home ] [ [463]Kermit
   Home ]
     _________________________________________________________________

  8.12. Pattern Matching

   A pattern is a character string that is used to match other strings.
   Patterns can contain metacharacters that represent special actions
   like "match any single character", "match zero or more characters",
   "match any single character from a list", and so on. The best known
   application of patterns is in file specifications that contain
   wildcards, as in "send *.txt", meaning "send all files whose names end
   with .txt".

   Patterns are also used in increasingly many other ways, to the extent
   it is useful to point out certain important distinctions in the ways
   in which they are used:

   Anchored Patterns
          If an anchored pattern does not begin with "*", it must match
          the beginning of the string, and if it does not end with "*",
          it must match the end of the string. For example, the anchored
          pattern "abc" matches only the string "abc", not "abcde" or
          "xyzabc" or "abcabc". The anchored pattern "abc*" matches any
          string that starts with "abc"; the anchored pattern "*abc"
          matches any string that ends with "abc"; the anchored pattern
          "*abc*" matches any string that contains "abc" (including any
          that start and/or end with it).

   Floating Patterns
          A floating pattern matches any string that contains a substring
          that matches the pattern. In other words, a floating pattern
          has an implied "*" at the beginning and end. You can anchor a
          floating pattern to the beginning by starting it with "^", and
          you can anchor it to the end by ending it with "$" (see
          examples below).

   Wildcards
          A wildcard is an anchored pattern that has the additional
          property that "*" does not match directory separators.

   This terminology lets us describe Kermit's commands with a bit more
   precision. When a pattern is used for matching filenames, it is a
   wildcard, except in the TEXT-PATTERNS and BINARY-PATTERNS lists and
   /EXCEPT: clauses, in which case directory separators are not
   significant (for example, a BINARY-PATTERN of "*.exe" matches any file
   whose name ends in .exe, no matter how deeply it might be buried in
   subdirectories). When Kermit parses a file specification directly,
   however, it uses the strict wildcard definition. For example, "send
   a*b" sends all files whose names start with "a" and end with "b" in
   the current directory, and not any files whose names end with "b" that
   happen to be in subdirectories whose names start with "a". And as
   noted, wildcards are anchored, so "delete foo" deletes the file named
   "foo", and not all files whose names happen to contain "foo".

   Most other patterns are anchored. For example:

  if match abc bc ...

   does not succeed (and you would be surprised if it did!). In fact, the
   only floating patterns are the ones used by commands or functions that
   search for patterns in files, arrays, or strings. These include:

     * The GREP and TYPE /MATCH commands.
     * The \fsearch(), \frsearch(), and \farraylook() functions.

   Thus these are the only contexts in which explicit anchors ("^" and
   "$") may be used:

   grep abc *.txt
          Prints all lines containing "abc" in all files whose names end
          with ".txt".

   grep ^abc *.txt
          Prints all lines that start with "abc" in all ".txt" files.

   grep abc$ *.txt
          Prints all lines that end with "abc" in all ".txt" files.

   grep ^a*z$ *.txt
          Prints all lines that start with "a" and end with "z" in all
          ".txt" files.

   Similarly for TYPE /PAGE, /fsearch(), /frsearch(), and \farraylook().

   Here is a brief summary of anchored and floating pattern equivalences:

  Anchored   Floating
    abc       ^abc$
    *abc      abc$
    abc*      ^abc
    *abc*     abc

   [ [464]Top ] [ [465]Contents ] [ [466]C-Kermit Home ] [ [467]Kermit
   Home ]
     _________________________________________________________________

  8.13. Dates and Times

   C-Kermit's comprehension of date-time formats is considerably expanded
   in version 8.0. Any command that reads dates, including the DATE
   command itself, or any switch, such as the /BEFORE: and /AFTER:
   switches, or any function such as \fcvtdate(), now can understand
   dates and times expressed in any ISO 8601 format, in Unix "asctime"
   format, in FTP MDTM format, and in practically any format used in RFC
   822 or RFC 2822 electronic mail, with or without timezones, and in a
   great many other formats as well. HELP DATE briefly summarizes the
   acceptable date-time formats.

   Furthermore, C-Kermit 8.0 includes a new and easy-to-use form of
   date-time arithmetic, in which any date or time can be combined with a
   "delta time", to add or subtract the desired time interval (years,
   months, weeks, days, hours, minutes, seconds) to/from the given date.
   And new functions are available to compare dates and to compute their
   differences.

   As you can imagine, all this requires quite a bit of "syntax". The
   basic format is:

  [ date ] [ time ] [ delta ]

   Each field is optional, but in most cases (depending on the context)
   there must be at least one field. If a date is given, it must come
   first. If no date is given, the current date is assumed. If no time is
   given, an appropriate time is supplied depending on whether a date was
   supplied. If no delta is given, no arithmetic is done. If a delta is
   given without a date or time, the current date and time are used as
   the base.

   Date-time-delta fields are likely to contain spaces (although they
   need not; space-free forms are always available). Therefore, in most
   contexts -- and notably as switch arguments -- date-time information
   must be enclosed in braces or doublequotes, for example:

  send /after:"8-Aug-2001 12:00 UTC" *.txt

   Kermit's standard internal format for dates and times is:

  yyyymmdd hh:mm:ss

   for example:

  20010208 10:28:01

   Date-times can always be given in this format. yyyy is the 4-digit
   year, mm is the two-digit month (1-12; supply leading zero for
   Jan-Sep), dd is the 2-digit day (leading zero for 1-9), hh is the hour
   (0-23), mm the minute (0-59), ss the second (0-59), each with leading
   zero if less than the field width. The date and time can be separated
   by a space, an underscore, a colon, or the letter T. The time is in
   24-hour format. Thus the various quantites are at the following fixed
   positions:

Position  Contents                    
   1-4    Year   (4 digits, 0000-9999)
   5-6    Month  (2 digits, 1-12)
   7-8    Day    (2 digits, 1-31)
   9      Date-Time Separator (space, :, _, or the letter T)
  10-11   Hour   (2 digits, 0-23)
  12      Hour-Minute Separator (colon)
  13-14   Minute (2 digits, 0-59)
  15      Minute-Second Separator (colon)
  16-17   Second (2 digits, 0-59)

   Example:

  19800526 13:07:12  26 May 1980, 13:07:12 (1:07:12PM)

   This is the format produced by the DATE command and by any function
   that returns a date-time. It is suitable for lexical comparison and
   sorting, and for use as a date-time in any Kermit command. When this
   format is given as input to a command or function, various date-time
   separators (as noted) are accepted:

  19800526 13:07:12  26 May 1980, 13:07:12 (1:07:12PM)
  20010208_10:28:35  2 February 2001, 10:28:35 AM
  18580101:12:00:00  1 January 1858, noon
  20110208T00:00:00  2 February 2011, midnight

   Certain other special date-time formats that are encountered on
   computer networks are recognized:

   Asctime Format
          This is a fixed format used by Unix, named after Unix's
          asctime() ("ASCII time") function. It is always exactly 24
          characters long. Example: Fri Aug 10 16:38:01 2001

   Asctime with Timezone
          This is like Asctime format, but includes a 3-character
          timezone between the time and year. It is exactly 28 characters
          long. Example: Fri Aug 10 16:38:01 GMT 2001

   E-Mail Format
          E-mail date-time formats are defined in [468]RFC 2822 with a
          fair amount of flexibility and options. The following examples
          are typical of e-mails and HTTP (web-page) headers:

  Sat, 14 Jul 2001 11:49:29                (No timezone)
  Fri, 24 Mar 2000 14:19:59 EST            (Symbolic timezone)
  Tue, 26 Jun 2001 10:19:45 -0400 (EDT)    (GMT Offset + comment)

   FTP MDTM Format
          This is the date-time format supplied by FTP servers that
          support the (not yet standard but widely used nevertheless)
          MDTM command, by which the FTP client asks for a file's
          modification time:

  yyyymmddhhmmss[.ffff]

          where yyyy is the 4-digit year, mm is the 2-digit month, and so
          on, exactly 14 digits long. An optional fractional part
          (fraction of second) may also be included, separated by a
          decimal point (period). Kermit rounds to the nearest second.
          Example:

  20020208102835.515                       (8 February 2002 10:28:36 AM)

    8.13.1. The Date

   The date, if given, must precede the time and/or delta, and can be in
   many, many formats. For starters, you can use several symbolic date
   names in place of actual dates:

   NOW
          This is replaced by the current date and time. The time can not
          be overriden (if you want to supply a specific time, use TODAY
          rather than NOW).

   TODAY
          This is replaced by the current date and a default time of
          00:00:00 is supplied, but can be overridden by a specific time;
          for example, if today is 8 February 2002, then "TODAY" is
          "20020802 00:00:00" but "TODAY 10:28" is "20020802 10:28:00".

   TOMORROW
          Like TODAY, but one day later (if today is 8 February 2002,
          then "TOMORROW" is "20020803 00:00:00" but "TOMORROW 16:30" is
          "20020803 16:30:00").

   YESTERDAY
          Like TODAY, but one day earlier.

   MONDAY, TUESDAY, WEDNESDAY, ..., SUNDAY
          The date on the given day of the week, today or later. A
          default time of 00:00:00 is supplied but can be overridden.
          Example: "SATURDAY 12:00" means next Saturday (or today, if
          today is Saturday) at noon.

   You can give an explicit date in almost any conceivable format, but
   there are some rules:

     * If a date is given, it must have three fields: day, month, and
       year; the order can vary (except that the month can not be last).
     * If names are used for days, months, etc, they must be English.
     * The year must lie between 0000 and 9999, inclusive.
     * All calendar calculations use Gregorian dating, so calculated
       dates for years prior to 1582 (or later, depending on the country)
       will not agree with historical dates. Other forms of dating (e.g.
       Hebrew, Chinese) are not supported.

   Various date-field separators are accepted: hyphen, slash, space,
   underscore, period. The same field separator (if any) must be used in
   both places; for example 18-Sep-2001 but not 18-Sep/2001. Months can
   be numeric (1-12) or English names or abbreviations. Month name
   abbreviations are normally three letters, e.g. Apr, May, Jun, Jul.
   Capitalization doesn't matter.

   Here are a few examples:

  18 Sep 2001                              (English month, abbreviated)
  18 September 2001                        (English month, spelled out)
  2001 Sept 18                             (Year, month, day)
  18-Sep-2001                              (With hyphens)
  18/09/2001                               (All numeric with slashes)
  18.09.2001                               (Ditto, with periods)
  18_09_2001                               (Ditto, with underscores)
  09/18/2001                               (See below)
  2001/09/18                               (See below)
  September 18, 2001                       (Correspondence style)
  Sep-18-2001                              (Month-day-year)
  20010918                                 (Numeric, no separators)

   You can also include the day of the week with a specific date, in
   which case it is accepted (if it is a valid day name), but not
   verified to agree with the given date:

  Tue, 18 Sep 2001                         (Abbreviated, with comma)
  Tue,18 Sep 2001                          (Comma but no space)
  Tue 18 Sep 2001                          (Abbreviated, no comma)
  Tuesday 18 Sep 2001                      (Spelled out)
  Tuesday, 18 Sep 2001                     (etc)
  Friday, 18 Sep 2001                      (Accepted even if not Friday)

   In all-numeric dates with the year last, such as 18/09/2001, Kermit
   identifies the year because it's 4 digits, then decides which of the
   other two numbers is the month or day based on its value. If both are
   12 or less and are unequal, the date is ambiguous and is rejected. In
   all-numeric dates with the year first, the second field is always the
   month and the third is the day. The month never comes last. A date
   with no separators is accepted only if it is all numeric and has
   exactly eight digits, and is assumed to be in yyyymmdd format.

  20010918                                 (18-Sep-2001 00:00:00)

   or 14 digits (as in FTP MDTM format):

  20010918123456                           (18-Sep-2001 12:34:56)

   You can always avoid ambiguity by putting the year first, or by using
   an English, rather than numeric, month. A date such as 09/08/2001
   would be ambiguous but 2001/09/08 is not, nor is 09-Aug-2001.

   Until the late 1990s, it was common to encounter 2-digit years, and
   these are found to this day in old e-mails and other documents. Kermit
   accepts these dates if they have English months, and interprets them
   according to the windowing rules of [469]RFC 2822: "If a two digit
   year is encountered whose value is between 00 and 49, the year is
   interpreted by adding 2000, ending up with a value between 2000 and
   2049. If a two digit year is encountered with a value between 50 and
   99, or any three digit year is encountered, the year is interpreted by
   adding 1900."

   If you need to specify a year prior to 1000, use leading zeros to
   ensure it is not misinterpreted as a "non-Y2K-compliant" modern year:

  7-Oct-77                                 (19771007 00:00:00)
  7-Oct-0077                               (00771007 00:00:00)

    8.13.2. The Time

   The basic time format is hh:mm:dd; that is hours, minutes, seconds,
   separated by colons, perhaps with an optional fractional second
   separated by a decimal point (period). The hours are in 24-hour
   format; 12 is noon, 13 is 1pm, and so on. Fields omitted from the
   right default to zero. Fields can be omitted from the left or middle
   by including the field's terminating colon. Examples:

  11:59:59                                 (11:59:59 AM)
  11:59                                    (11:59:00 AM)
  11                                       (11:00:00 AM)
  11:59:59.33                              (11:59:59 AM)
  11:59:59.66                              (Noon)
  03:21:00                                 (3:21:00 AM)
  3:21:00                                  (3:21:00 AM)
  15:21:00                                 (3:21:00 PM)
  :21:00                                   (00:21:00 AM)
  ::01                                     (00:00:01 AM)
  11::59                                   (11:00:59 AM)

   Leading zeros can be omitted, but it is customary and more readable to
   keep them in the minute and second fields:

  03:02:01                                 (03:02:01 AM)
  3:02:01                                  (03:02:01 AM)
  3:2:1                                    (03:02:01 AM)

   AM/PM notation is accepted if you wish to use it:

  11:59:59                                 (11:59:59 AM)
  11:59:59AM                               (11:59:59 AM)
  11:59:59A.M.                             (11:59:59 AM)
  11:59:59am                               (11:59:59 AM)
  11:59:59a.m.                             (11:59:59 AM)
  11:59:59PM                               (11:59:59 PM = 23:59:59)
  11:59:59P.M.                             (11:59:59 PM = 23:59:59)
  11:59:59pm                               (11:59:59 PM = 23:59:59)
  11:59:59p.m.                             (11:59:59 PM = 23:59:59)

   You can omit the colons if you wish, in which case Kermit uses the
   following rules to interpret the time:

    1. 6 digits is hh:mm:ss, e.g. 123456 is 12:34:56.
    2. 5 digits is h:mm:ss, e.g. 12345 is 1:23:45.
    3. 4 digits is hh:mm, e.g. 1234 is 12:34.
    4. 3 digits is h:mm, e.g. 123 is 1:23.
    5. 2 digits is hh, e.g. 12 is 12:00.
    6. 1 digit is h (the hour), e.g. 1 is 1:00.

   Examples:

  1                                        (01:00:00 AM)
  10                                       (10:00:00 AM)
  230                                      (02:30:00 AM)
  230pm                                    (02:30:00 PM = 14:30:00)
  1115                                     (11:15:00 AM)
  2315                                     (11:15:00 PM = 23:15:00 PM)
  23150                                    (02:31:50 AM)
  231500                                   (23:15:00 PM)

    8.13.3. Time Zones

   If a time is given, it can (but need not) be followed by a time zone
   designator. If no time zone is included, the time is treated as local
   time and no timezone conversions are performed.

   The preferred time zone designator is the UTC Offset, as specified in
   [470]RFC 2822: a plus sign or minus sign immediately followed by
   exactly four decimal digits, signifying the difference in hh (hours)
   and mm (minutes) from Universal Coordinated Time (UTC, also known as
   Greenwich Mean Time, or GMT), with negative numbers to the West and
   positive numbers to the East. For example:

  Fri, 13 Jul 2001 12:54:29 -0700

   indicates a local time of 12:54:29 that is 07 hours and 00 minutes
   behind (less than, East of) Universal Time. The space is optional, so
   the example could also be written as:

  Fri, 13 Jul 2001 12:54:29-0700

   The following symbolic time zones are also accepted, as specified by
   [471]RFC 2822 and/or in ISO 8601:

  GMT  =  +0000       Greenwich Mean Time
  Z    =  +0000       Zulu (Zero Meridian) Time
  UTC  =  +0000       Universal Coordinated Time
  UT   =  +0000       Universal Time
  EDT  =  -0400       Eastern (USA) Daylight Time
  EST  =  -0500       Eastern (USA) Standard Time
  CDT  =  -0500       Central (USA) Daylight Time
  CST  =  -0600       Central (USA) Standard Time
  MDT  =  -0600       Mountain (USA) Daylight Time
  MST  =  -0700       Mountain (USA) Standard Time
  PDT  =  -0700       Pacific (USA) Daylight Time
  PST  =  -0800       Pacific (USA) Standard Time

   Note that GMT, Z, UTC, and UT all express the same concept: standard
   (not daylight) time at the Zero Meridian. UTC, by the way, is an
   international standard symbol and does not correspond to the order of
   the English words, Universal Coordinated Time, but it happens to have
   the same initial letters as these words. Of course hundreds of other
   symbolic timezones and variations exist, but they are not
   standardized, and are therefore not supported by Kermit.

   When a time zone is included with a time, the time is converted to
   local time. In case the conversion crosses a midnight boundary, the
   date is adjusted accordingly. Examples converting to EST (Eastern USA
   Standard Time = -0500):

 11:30:00      =  11:30:00
 11:30:00 EST  =  11:30:00
 11:30:00 GMT  =  06:30:00
 11:30:00 PST  =  14:30:00
 11:30:00Z     =  06:30:00
 11:30PM GMT   =  18:30:00
 11:30 -0500   =  11:30:00
 11:30 -0800   =  08:30:00
 11:30 +0200   =  04:30:00

   Unlike most of Kermit's other date-time conversions, timezone
   knowledge (specifically, the offset of local time from UTC) is
   embodied in the underlying operating system, not in Kermit itself, and
   any conversion errors in this department are the fault of the OS. For
   example, most UNIX platforms do not perform conversions for years
   prior to 1970.

    8.13.4. Delta Time

   Date/time expressions can be composed of a date and/or time and a
   delta time, or a delta time by itself. When a delta time is given by
   itself, it is relative to the current local date and time. Delta times
   have the following general format:

  {+,-}[number units][hh[:mm[:ss]]]

   In other words, a delta time always starts with a plus or minus sign,
   which is followed by a "part1", a "part2", or both. The "part1", if
   given, specifies a number of days, weeks, months, or years; "part2"
   specifies a time in hh:mm:ss notation. In arithmetic terms, these
   represents some number of days or other big time units, and then a
   fraction of a day expressed as hours, minutes, and seconds; these are
   to be added to or subtracted from the given (or implied) date and
   time. The syntax is somewhat flexible, as shown by the following
   examples:

  +1 day                (Plus one day)
  +1day                 (Ditto)
  +1d                   (Ditto)
  + 1 day               (Ditto)
  + 1 day 3:00          (Plus one day and 3 hours)
  +1d3:00               (Ditto)
  +1d3                  (Ditto)
  +3:00:00              (Plus 3 hours)
  +3:00                 (Ditto)
  +3                    (Ditto)
  +2 days               (Plus 2 days)
  -12 days 7:14:22      (Minus 12 days, 7 hours, 14 minutes, and 22 seconds)

   The words "week", "month", and "year" can be used like "day" in the
   examples above. A week is exactly equivalent to 7 days. When months
   are specified, the numeric month number of the date is incremented or
   decremented by the given number, and the year and day adjusted
   accordingly if necessary (for example, 31-Jan-2001 +1month =
   03-Mar-2001 because February does not have 31 days). When years are
   specified, they are added or subtracted to the base year. Examples
   (assuming the current date is 10-Aug-2001 and the current time is
   19:21:11):

  18-Sep-2001 +1day              (20010918 00:00:00)
  today +1day                    (20010811 00:00:00)
  now+1d                         (20010811 19:21:11)
  + 1 day                        (20010811 19:21:11)
  + 1 day 3:14:42                (20010811 22:35:54)
  + 7 weeks                      (20010928 19:21:11)
  +1d3:14:42                     (20010811 22:35:54)
  +1w3:14:42                     (20010817 22:35:54)
  +1m3:14:42                     (20010910 22:35:54)
  +1y3:14:42                     (20020810 22:35:54)
  2 feb 2001 + 10 years          (20110208 00:00:00)
  2001-02-08 +10y12              (20110208 12:00:00)
  31-dec-1999 23:59:59+00:00:01  (20000101 00:00:00)
  28-feb-1996 +1day              (19960229 00:00:00) (leap year)
  28-feb-1997 +1day              (19970301 00:00:00) (nonleap year)
  28-feb-1997 +1month            (19970328 00:00:00)
  28-feb-1997 +1month 11:59:59   (19970328 11:59:59)
  28-feb-1997 +20years           (20170228 00:00:00)
  28-feb-1997 +8000years         (99970228 00:00:00)

   For compatibility with VMS, the following special delta-time format is
   also accepted:

  +number-hh:mm:ss
  -number-hh:mm:ss

   (no spaces). The hyphen after the number indicates days. It
   corresponds exactly to the Kermit notation:

  +numberdhh:mm:ss
  -numberdhh:mm:ss

   The following forms all indicate exactly the same date and time:

  18-Sep-2001 12:34:56 +1-3:23:01
  18-Sep-2001 12:34:56 +1d3:23:01
  18-Sep-2001 12:34:56 +1 day 3:23:01

   and mean "add a day plus 3 hours, 23 minutes, and 1 second" to the
   given date.

   Note that delta times are not at all the same as UTC offsets; the
   former specifies an adjustment to the given date/time and the latter
   specifies that the local time is a particular distance from Universal
   Time, for example:

  11-Aug-2001 12:34:56 -0800          (20010811 16:34:56 -- UTC Offset)
  11-Aug-2001 12:34:56 -08:00         (20010811 04:34:56 -- Delta time)

   If you give a time followed by a modifer that starts with a + or -
   sign, how does Kermit know whether it's a UTC offset or a delta time?
   It is treated as a UTC offset if the sign is followed by exactly four
   decimal digits; otherwise it is a delta time. Examples (for USA
   Eastern Daylight Time):

  11-Aug-2001 12:34:56 -0800          (20010811 16:34:56 -- UTC Offset)
  11-Aug-2001 12:34:56 -08:00         (20010811 04:34:56 -- Delta time)
  11-Aug-2001 12:34:56 -800           (20010811 04:34:56 -- Delta time)
  11-Aug-2001 12:34:56 -8             (20010811 04:34:56 -- Delta time)

   The first example says that at some unknown place which is 8 hours
   ahead of Universal Time, the time is 12:34:56, and this corresponds to
   16:34:56 in Eastern Daylight time. The second example says to subtract
   8 hours from the local time. The third and fourth are delta times
   because, even though a colon is not included, the time does not
   consist of exactly 4 digits.

   When a delta time is written after a timezone, however, there is no
   ambiguity and no syntax distinction is required:

  11-Aug-2001 12:34:56 -0800 -0800    (20010811 08:34:56)
  11-Aug-2001 12:34:56 -0800 -08:00   (Ditto)
  11-Aug-2001 12:34:56 -08:00 -08:00  (Illegal)

    8.13.5. The DATE Command

   Obviously a great many combinations of date, time, time zone, and
   delta time are possible, as well as many formatting options. The
   purpose of all this flexibility is to comply with as many standards as
   possible -- Internet RFCs, ISO standards, and proven corporate
   standards -- as well as with notations commonly used by real people,
   in order that dates and times from the widest variety of sources can
   be assigned to a variable and used in any date-time field in any
   Kermit command.

   You can test any date-and/or-time format with the DATE command, which
   converts it to standard yyyymmdd hh:mm:ss format if it is understood,
   or else gives an explicit error message (rather than just "BAD DATE"
   as in previous C-Kermit releases) to indicate what is wrong with it.
   Examples (on Tuesday, 31 July 2001 in New York City, Eastern Daylight
   Time, UTC -0400):

  DATE command argument                   Result           
  12:30                                   20010731 12:30:00
  12:30:01                                20010731 12:30:01
  12:30:01.5                              20010731 12:30:02
  1230                                    20010731 12:30:00
  230                                     20010731 02:30:00
  230+1d                                  20010801 02:30:00
  230+1d3:00                              20010801 05:30:00
  20010718 19:21:15                       20010718 19:21:15
  20010718_192115                         20010718 19:21:15
  20010718T192115                         20010718 19:21:15
  18 Jul 2001 +0400                       20010717 23:59:59
  18 Jul 2001 192115                      20010718 19:21:15
  18 Jul 2001 192115.8                    20010718 19:21:16
  18-Jul-2001T1921                        20010718 19:21:00
  18-Jul-2001 1921Z                       20010718 15:21:00
  18-Jul-2001 1921 GMT                    20010718 15:21:00
  18-Jul-2001 1921 UTC                    20010718 15:21:00
  18-Jul-2001 1921 Z                      20010718 15:21:00
  18-Jul-2001 1921Z                       20010718 15:21:00
  18-Jul-2001 1921 -04:00:00              20010718 19:21:00
  21-Jul-2001_08:20:00am                  20010721 08:20:00
  21-Jul-2001_8:20:00P.M.                 20010721 20:20:00
  Fri Jul 20 11:26:25 2001                20010720 11:26:25
  Fri Jul 20 11:26:25 GMT 2001            20010720 07:26:25
  Sun, 9 Apr 2000 06:46:46 +0100          20000409 01:46:46
  Sunday, 9 Apr 2000 06:46:46 +0100       20000409 01:46:46
  now                                     20010731 19:41:12
  today                                   20010731 00:00:00
  today 09:00                             20010731 09:00:00
  tomorrow                                20010801 00:00:00
  tomorrow 09:00                          20010801 09:00:00
  tomorrow 09:00 GMT                      20010801 05:00:00
  yesterday                               20010730 00:00:00
  yesterday 09:00                         20010730 09:00:00
  + 3 days                                20010803 00:00:00
  +3 days                                 20010803 00:00:00
  +3days                                  20010803 00:00:00
  + 3days                                 20010803 00:00:00
  + 3 days 09:00                          20010803 09:00:00
  + 2 weeks                               20010814 00:00:00
  + 1 month                               20010831 00:00:00
  - 7 months                              20001231 00:00:00
  + 10 years                              20110731 00:00:00
  friday                                  20010803 00:00:00
  saturday                                20010804 00:00:00
  sunday                                  20010805 00:00:00
  monday                                  20010806 00:00:00
  tuesday                                 20010731 00:00:00
  wednesday                               20010801 00:00:00
  thursday                                20010802 00:00:00
  friday 07:00                            20010803 07:00:00
  thursday 1:00pm                         20010802 13:00:00
  thursday 1:00pm GMT                     20010802 09:00:00
  Thu, 10 Nov 94 10:50:47 EST             19941110 10:50:47
  Fri, 20 Oct 1995 18:35:15 -0400 (EDT)   19951020 18:35:15
  31/12/2001                              20011231 00:00:00
  12/31/2001                              20011231 00:00:00
  2001-July-20                            20010720 00:00:00
  2001-September-30                       20010930 00:00:00
  30-September-2001                       20010930 00:00:00
  Sep 30, 2001 12:34:56                   20010930 12:34:56
  September 30, 2001                      20010930 00:00:00
  September 30, 2001 630                  20010930 06:30:00
  September 30 2001 630                   20010930 06:30:00
  Sep-30-2001 12:34:59                    20010930 12:34:59
  20010807113542.014                      20010807 11:35.42
  20010807113542.014Z                     20010807 07:35:42

    8.13.6. New Date-Time Functions

   In the following descriptions, date-time function arguments are the
   same free-format date-time strings discussed above, with the same
   defaults for missing fields. They are automatically converted to
   standard format internally prior to processing.

   \fcvtdate(d1)
          Converts the date-time d1 to standard format and local time.
          This function is not new, but now it accepts a wider range of
          argument formats that can include timezones and/or delta times.
          If the first argument is omitted, the current date and time are
          assumed. The optional second argument is a format code for the
          result:

     n1 = 1: yyyy-mmm-dd hh:mm:ss (mmm = English 3-letter month
     abbreviation)
     n1 = 2: dd-mmm-yyyy hh:mm:ss (ditto)
     n1 = 3: yyyymmddhhmmss (all numeric)

   \futcdate(d1)
          Converts the date-time d1 to Universal Coordinated Time (UTC),
          also known as GMT or Zulu or Zero-Meridian time. The default d1
          is NOW. If d1 is a valid date-time, the UTC result is returned
          in standard format, yyyymmdd hh:ss:mm.

   \fcmpdates(d1,d2)
          Compares two free-format date-times, d1 and d2, and, if both
          arguments are valid, returns a number: -1 if d1 is earlier than
          (before) d2; 0 if d1 is the same as d2; 1 if d1 is later than
          (after) d2.

   \fdiffdates(d1,d2)
          Computes the difference between two free-format date-times, d1
          and d2. If both arguments are valid, returns a delta time which
          is negative if d1 is earlier than (before) d2 and positive
          otherwise. If d1 and d2 are equal, the result is "+0:00".
          Otherwise, the result consists of the number of days, hours,
          minutes, and seconds that separate the two date-times. If the
          number of days is zero, it is omitted. If the number of days is
          nonzero but the hours, minutes, and seconds are all zero, the
          time is omitted. if the seconds are zero, they are omitted.

   \fdelta2secs(dt)
          Converts a delta time to seconds. For example, "+1d00:00:01" to
          86401. Valid delta times must start with a + or - sign. Days
          are accepted as time units, but not years, months, or weeks. If
          the result would overflow a computer long word (as would happen
          with 32-bit long words when the number of days is greater than
          24854), the function fails.

   HINT: Although Kermit has a number of built-in date and time
   variables, it doesn't have a single one suitable for writing a
   timestamp. For this you would normally use something like "\v(ndate)
   \v(time)". But \fcvtdate() (with no arguments) is equivalent: it
   returns the current date and time in yyyymmdd hh:mm:ss format,
   suitable for time stamping.

    8.13.7. Date-Time Programming Examples

   Here's a macro that converts any date-time to UTC, which you might use
   if C-Kermit didn't already have a \futcdate() function:

  define utcdate {
      .local := \fcvtdate(\%*)                 ; 1.
      .tmp := \fcvtdate(\m(local)UTC)          ; 2.
      .offset := \fdiffdate(\m(local),\m(tmp)) ; 3.
      .utc := \fcvtdate(\m(local)\m(offset))   ; 4.
      sho mac utc                              ; 5.
  }

   Brief explanation: Line 1 converts the macro argument, a free-format
   date-time, to standard-format local time. Line 2 appends the "UTC"
   timezone to the local time and converts the result to local time. In
   other words, we take the same time as the local time, but pretend it's
   UTC time, and convert it to local time. For example, if New York time
   is 4 hours ahead of UTC, then 6:00pm New York time is 2:00pm UTC. Line
   3 gets the difference of the two results (e.g. "+04:00"). Line 4
   appends the difference (delta time) to the local time, and converts it
   again, which adds (or subtracts) the UTC offset to the given time.
   Line 5 displays the result.

   Here's a script that opens a web page, gets its headers into an array,
   scans the array for the "Last-Modified:" header, and inteprets it:
  http open www.columbia.edu
  if fail stop 1 HTTP OPEN failed
  http /array:a head index.html /dev/null
  if fail stop 1 HTTP GET failed
  show array a
  for \%i 1 \fdim(&a) 1 {
      .\%x := \findex(:,\&a[\%i])
      if not \%x continue
      .tag := \fleft(\&a[\%i],\%x-1)
      .val := \fltrim(\fsubstr(\&a[\%i],\%x+1))
      if ( eq "\m(tag)" "Last-Modified" ) {
          echo HTTP Date: \m(val)
          .rdate := \fcvtdate(\m(val))
          echo {Standard Date (local): \m(rdate)}
          echo {Standard Date (UTC):   \futcdate(\m(rdate))}
          break
      }
  }
  http close

   The result:

  HTTP Date: Mon, 13 Aug 2001 20:05:42 GMT
  Standard Date (local): 20010813 16:05:42
  Standard Date (UTC):   20010813 20:05:42

   As you can see, Kermit had no trouble decoding the date-time-string
   from the website, converting to local time, and converting back to UTC
   with no conflicts or loss of information. If it had been in any other
   known format, the result would have been the same.

   Now suppose we want to download the web page only if it is newer than
   our local copy. The \fdate(filename) function (which returns the
   modification date-time of the given file) and the new \fcmpdates()
   function make it easy. Insert the following just before the BREAK
   statement:

  if ( < 0 \fcmpdates(\m(rdate),\fdate(index.html)) ) {
     echo GETTING index.html...
     http get index.html index.html
     if success echo HTTP GET OK
  } else {
     echo index.html: no update needed
  }
  http close
  exit

   This says, "if 0 is less than the comparison of the remote file date
   and the local file date, get the remote file, otherwise skip it." And
   it automatically reconciles the time-zone difference (if any).

   It would be nice to be able to extend this script into a
   general-purpose website updater, but unfortunately HTTP protocol
   doesn't provide any mechanism for the client to ask the server for a
   list of files, recursive or otherwise.

   [ [472]Top ] [ [473]Contents ] [ [474]C-Kermit Home ] [ [475]Kermit
   Home ]
     _________________________________________________________________

  8.14. Trapping Keyboard Interruption

   Normally when you type Ctrl-C and Kermit is in command mode (as
   opposed to CONNECT mode) with COMMAND INTERRUPTION ON (as it is unless
   you have set it OFF), Kermit interrupts any command that is currently
   in progress, and if a command file or macro is executing, rolls the
   command stack back to top level, closing all open command files,
   deactivating all macros, deallocating all local variables and arrays,
   and leaving you at the command prompt.

   Suppose, however, you want certain actions to occur when a script is
   interrupted; for example, closing open files, writing log entries, or
   displaying summary results. You can do this by defining a macro named
   ON_CTRLC. When Ctrl-C is detected, and a macro with this name is
   defined, Kermit executes it from the current command level, thus
   giving it full access to the environment in which the interruption
   occurred, including local variables and open files. Only when the
   ON_CTRLC macro completes execution is the command stack rolled back to
   top level.

   Once the ON_CTRLC macro is defined, it can be executed only once. This
   is to prevent recursion if the user types Ctrl-C while the ON_CTRLC
   macro is executing. If you type Ctrl-C while the Ctrl-C macro is
   active, this does not start a new copy of ON_CTRLC; rather, it returns
   to the top-level command prompt. After the ON_CTRLC macro returns, it
   has been removed from the macro table so if you want to use it again
   or install a different Ctrl-C trap, you must execute a new DEFINE
   ON_CTRLC command. In any case, as always when you interrupt a script
   with Ctrl-C, its completion status is FAILURE.

   Normally the ON_CTRLC macro would be defined in the command file or
   macro to which it applies, and should be declared LOCAL. This way, if
   the command file or macro completes successfully without being
   interrupted, the ON_CTRLC definition disappears automatically.
   Otherwise the definition would still be valid and the macro would be
   executed, probably out of context, the next time you typed Ctrl-C.

   Here's a simple example of a command file that sets a Ctrl-C trap for
   itself:

  local on_ctrlc              ; Make Ctrl-C trap local to this command file.
  define on_ctrlc {           ; Define the ON_CTRLC macro.
      echo Interrupted at \v(time).
      echo Iterations: \%n
  }
  xecho Type Ctrl-C to quit
  for \%n 1 999 1 {           ; Prints a dot every second until interrupted.
      sleep 1
      xecho .
  }
  echo Finished normally at \v(time) ; Get here only if not interrupted.
  decrement \%n
  echo Iterations: \%n

   This prints a summary no matter whether it completes normally or is
   interrupted from the keyboard. In both cases the trap is automatically
   removed afterwards.

   For an example of how to use ON_CTRLC to debug scripts, see
   [476]Section 8.1.

   [ [477]Top ] [ [478]Contents ] [ [479]C-Kermit Home ] [ [480]Kermit
   Home ]
  __________________________________________________________________________

9. S-EXPRESSIONS

   This section is primarily for those who want to write
   calculation-intensive scripts, especially if they require
   floating-point arithmetic, and/or for those who are familiar with the
   LISP programming language.

   Ever since C-Kermit version 5 was released in 1988, scripting has been
   one of its major attractions, and arithmetic is a key part of it.
   Versions 5 and 6 included integer arithmetic only, using traditional
   algebraic notation, e.g.:

  echo \fevaluate(3*(2+7)/2)
  13

   C-Kermit 7.0 added support for floating-point arithmetic, but only
   through function calls:

  echo \ffpdivide(\ffpmultiply(3.0,\ffpadd(2.0,7.0)),2.0)
  13.5

   C-Kermit 8.0 introduces a third form of arithmetic that treats
   integers and floating-point numbers uniformly, is easier to read and
   write, and executes very quickly:

  (/ (* 3 (+ 2 7)) 2)
  13.5

   But first some background.

   The Kermit command and scripting language differs from true
   programming languages (such as C or Fortran) in many ways; one of the
   most prominent differences is the way in which variables are
   distinguished from constants. In a command language, words are taken
   literally; for example, the Unix shell:

  cat foo.bar

   displays the file named foo.bar. Whereas in a programming language
   like C, words are assumed to be variables:

  s = foo.bar;    /* Assigns the value of foo.bar to the variable s */

   To make a programming language take words literally, you have to quote
   or "escape" them:

  s = "foo.bar";  /* Assigns a pointer to the string "foo.bar" to the variable
s */

   The opposite holds for command languages: to get them to treat a word
   as a variable rather than a constant, you have to escape them. For
   example, in the Unix shell:

  foo=123         ; Assign value 123 to variable foo.
  echo foo        ; Prints "foo"
  echo $foo       ; Prints "123"

   And in Kermit:

  define foo 123  ; Assign value 123 to variable foo.
  echo 123        ; This prints "123".
  echo foo        ; This prints "foo".
  echo \m(foo)    ; This prints "123".

   In other words, character strings (such as "foo" above) are
   interpreted as literal strings, rather than variable names, except in
   special commands like DEFINE that deal specifically with variable
   names (or in numeric contexts as explained in [481]Section 8.2). The
   special "escape" character (dollar sign ($) for the shell, backslash
   (\) for Kermit) indicates that a variable is to be replaced by its
   value.

   The requirement to escape variable names in command languages normally
   does not impose any special hardship, but can add a considerable
   notational burden to arithmetic expressions, which are typically full
   of variables. Especially in Kermit when floating point numbers are
   involved, where you must use special \ffpxxx() functions, e.g.
   "\ffpadd(\m(a),\m(b))" rather than the simple "+" operator to add two
   floating-point numbers together, because the original arithmetic
   handler doesn't support floating point (this might change in the
   future). To illustrate, the general formula for the area of a triangle
   is:

  sqrt(s * (s - a) * (s - b) * (s - c))

   where a, b, and c are the lengths of the triangle's three sides and:

  s = (a + b + c) / 2

   Except in special cases (e.g. a = 3, b = 4, c = 5), the result has a
   fractional part so the computation must be done using floating-point
   arithmetic. We can create a Kermit 7.0 function for this as follows:

  def area {
      local s t1 t2 t3
      assign s \ffpdiv(\ffpadd(\ffpadd(\%1,\%2),\%3),2.0)
      assign t1 \ffpsub(\m(s),\%1)
      assign t2 \ffpsub(\m(s),\%2)
      assign t3 \ffpsub(\m(s),\%3)
      return \ffpsqrt(\ffpmul(\m(s),\ffpmul(\m(t1),\ffpmul(\m(t2),\m(t3)))))
  }

   But as you can see, this is rather cumbersome. Note, in particular,
   that arithmetic functions like \ffpadd(), \ffpmul(), etc, take exactly
   two operands (like their symbolic counterparts + and *), so obtaining
   the product of three or more numbers (as we do in this case) is
   awkward.

   Using the alternative S-Expression notation, we can reduce this to a
   form that is both easier to read and executes faster (the details are
   explained later):

  def newarea {
      (let s (/ (+ \%1 \%2 \%3) 2.0))
      (sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  }

   In both examples, the \%1..3 variables are the normal Kermit macro
   arguments, referenced by the normal escaping mechanism. For increased
   readability, we can also assign the macro arguments \%1, \%2, and \%3
   to the letters a, b, and c corresponding to our formula:

def newarea {
    (let a \%1 b \%2 c \%3)
    (let s (/ (+ a b c) 2.0))
    (sqrt (* s (- s a) (- s b) (- s c)))
}

   And now the Kermit function reads almost like the original formula.
   Here Kermit behaves more like a regular programming language. In an
   S-Expression, macro names need not be escaped when they are used as
   the names of numeric variables.

   [ [482]Top ] [ [483]Contents ] [ [484]C-Kermit Home ] [ [485]Kermit
   Home ]
     _________________________________________________________________

  9.1. What is an S-Expression?

   The S-Expression concept is borrowed from the Lisp programming
   language. "S-Expression" is short for Symbolic Expression (itself
   sometimes shortened to SEXP). S-Expressions provide a kind of
   Alternative Mini-Universe within the Kermit command language when the
   regular rules don't apply, a universe enclosed in parentheses.

   C-Kermit does not pretend to be a full Lisp interpreter; only the
   arithmetic parts of Lisp have been incorporated: S-Expressions that
   operate on numbers and return numeric values (plus extensibility
   features described in [486]Section 9.8, which allow some degree of
   string processing).

   An S-Expression is a list of zero or more items, separated by spaces,
   within parentheses. Examples:

  ()
  (1)
  (a)
  (+ a 1)
  (* 2 a b)

   If the S-Expression is empty, it has the NIL (empty) value. If it is
   not empty and the first item is an operator (such as + or *), there
   can be zero or more subsequent items, called the operands:

  (+ 1 2)

   Here the operator is "+" and the operands are "1" and "2", and the
   value of the S-Expression is the value of the operation (in this case
   3). The operator always comes first, which is different from the
   familiar algebraic notation; this because S-Expression operators can
   have different numbers of operands:

  (+ 1)
  (+ 1 2)
  (+ 1 2 3 4 5 6 7 8 9)

   If the first item in the S-Expression is not an operator, then it must
   be a variable or a number (or a macro; see [487]Section 9.8), and the
   S-Expression can only contain one item; in this case, the
   S-Expression's value is the value of the variable or number:

  (a)
  (3)

   Operands can be numbers, variables that have numeric values, functions
   that return numbers, or other S-Expressions. To illustrate an
   S-Expression within an S-Expression, observe that:

  (+ 1 2)

   is equivalent to any of the following (plus an infinite number of
   others):

  (+ 1 (+ 1 1))
  (+ (- 3 2) (/ 14 (+ 3 4)))

   S-Expressions can be nested to any reasonable level; for example, the
   value of the following S-Expression is 64:

  (- (* (+ 2 (* 3 4)) (- 9 (* 2 2))) 6)

   Operators have no precedence, implied or otherwise, since they can't
   be mixed. The only exceptions are unary + and -, which simply indicate
   the sign of a number:

  (* 3 -1)

   Order of evaluation is specified entirely by parentheses, which are
   required around each operator and its operands: (+ a (* b c)) instead
   of (a + b * c).

   S-Expressions provide a simple and isolated environment in which
   Kermit's macro names can be used without the \m(...) escaping that is
   normally required. Given:

  define a 1
  define b 2
  define c 3

   Then:

  (+ \m(a) \m(b) \m(c))

   is equivalent to:

  (+ a b c)

   Within an S-Expression, as in other strictly numeric contexts
   ([488]Section 8.2), any operand that starts with a letter is treated
   as a Kermit macro name. In this context, abbreviations are not
   accepted; variable names must be spelled out in full. Alphabetic case
   is not significant; "a" and "A" are the same variable, but both are
   different from "area".

   Of course, regular Kermit variables and functions can be used in
   S-Expressions in the normal ways:

  (* \v(math_pi) (^ \%r 2))             ; Area of a circle with radius \%r
  (+ \fjoin(&a))                        ; Sum of all elements of array \&a[]

   [ [489]Top ] [ [490]Contents ] [ [491]C-Kermit Home ] [ [492]Kermit
   Home ]
     _________________________________________________________________

  9.2. Integer and Floating-Point-Arithmetic

   Normally, if all numbers in an S-Expression are integers, the result
   is an integer:

  (+ 1 1)                               ; Result is 2
  (/ 9 3)                               ; Result is 3

   If any of the operands is floating point, however, the result is also
   floating point:

  (+ 1 1.0)                             ; Result is 2.0
  (/ 9.0 3)                             ; Result is 3.0

   If all the operands are integers but the result has a fractional part,
   the result is floating point:

  (/ 10 3)                              ; Result is 3.333333333333333

   To force an integer result in such cases, use the TRUNCATE operator:

  (truncate (/ 10 3))                   ; Result is 3

   Similarly, to force a computation to occur in floating point, you can
   coerce one of its operands to FLOAT:

  (+ 1 (float 1))                       ; Result is 2.0

   The result is also floating point if the magnitude of any integer
   operand, intermediate result, or the result itself, is larger than the
   maximum for the underlying machine architecture:

  (^ 100 100)

   If the result is too large even for floating-point representation,
   "Infinity" is printed; if it is too small to be distinguished from 0,
   0.0 is returned.

   Large numbers can be used and large results generated, but they are
   accurate only to the precision of the underlying machine. For example,
   the result of:

 (+ 111111111111111111111 222222222222222222222)

   should be 333333333333333333333, but 333333333333333300000.0 is
   produced instead if the machine is accurate to only about 16 decimal
   digits, even with coercion to floating-point. The order of magnitude
   is correct but the least significant digits are wrong. The imprecise
   nature of the result is indicated by the ".0" at the end. Contrast
   with:

 (+ 111111111 222222222)

   which produces an exact integer result.

   [ [493]Top ] [ [494]Contents ] [ [495]C-Kermit Home ] [ [496]Kermit
   Home ]
     _________________________________________________________________

  9.3. How to Use S-Expressions

   S-Expressions may be given as commands to C-Kermit. Any command whose
   first character is "(" (left parenthesis) is interpreted as an
   S-Expression.

   If you enter an S-Expression at the C-Kermit> prompt, its result is
   printed:

  C-Kermit>(/ 10.0 3)
   3.333333333333333
  C-Kermit>

   If an S-Expression is executed within a macro or command file, its
   value is not printed. However, you can control the printing action
   with:

   SET SEXPRESSION ECHO { AUTO, ON, OFF }
          AUTO is the default, meaning print the value at top level only;
          ON means always print the value; OFF means never print it.

   In any case, the value of the most recent S-Expression (and the
   S-Expression itself) may be accessed programmatically through the
   following variables:

   \v(sexpression)
          The S-Expression most recently executed.

   \v(svalue)
          The value of the S-Expression most recently executed.

   Besides issuing S-Expressions as commands in themselves, you can also
   execute them anywhere within a Kermit command, but in this case they
   must be enclosed in a function call (otherwise they are taken
   literally):

   \fsexpression(s)
          The argument "s" is an S-Expression; the outer parentheses may
          be omitted. The value of the S-Expression is returned. Note
          that since S-Expressions usually contain spaces, some form of
          grouping or quoting might be needed in some contexts:

  echo \fsexpression((+ 1 1))            ; Outer parentheses may be included
  echo \fsexpr(+ 1 1)                    ; Outer parentheses may be omitted
  echo Value = "\fsexp(+ 1 a)"           ; Can be embedded in strings
  echo Value = \&a[\fsexp(/ b 2)]        ; Can be used in array subscripts
  if = {\fsexp(+ 1 1)} 2 {               ; Braces needed here for grouping
      echo One plus one still equals two
  }

   The IF statement illustrates how to use S-Expressions as (or in) IF or
   WHILE conditions:

     * Although S-Expressions and IF conditions are similar in
       appearance, they are not interchangeable. Therefore you must use
       \fsexpr() to let Kermit know it's an S-Expression rather than a
       regular IF condition, or a boolean or algebraic expression within
       an IF condition.
     * In contexts where a single "word" is expected, you must enclose
       the \fsexp() invocation in braces if the S-Expression contains
       spaces (and most of them do).

   If an S-Expression is the last command executed in a macro, its value
   becomes the return value of the macro; no RETURN command is needed.
   Example:

  def newarea {
      (let s (/ (+ \%1 \%2 \%3) 2.0))
      (sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  }

   This is equivalent to (but more efficient than):

  def newarea {
      (let s (/ (+ \%1 \%2 \%3) 2.0))
      return \fsexp(sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  }

   When an S-Expression is entered as a command -- that is, the first
   nonblank character of the command is a left parenthesis -- then it is
   allowed to span multiple lines, as many as you like, until the first
   left parenthesis is matched:

  (let s (/
          (+
           \%1
           \%2
           \%3
           )
          2.0
          )
       )
  (sqrt (*
         s
         (- s \%1)
         (- s \%2)
         (- s \%3)
         )
        )

   The S-Expression concept lends itself easily to embedding and
   recursion, but the depth to which recursion can occur is limited by
   the resources of the computer (memory size, address space, swap space
   on disk) and other factors. There is no way that C-Kermit can know
   what this limit is, since it varies not only from computer to
   computer, but also from moment to moment. If resources are exhausted
   by recursion, C-Kermit simply crashes; there's no way to trap this
   error. However, you can set a depth limit on S-Expressions:

   SET SEXPRESSION DEPTH-LIMIT number
          Limits the number of times the S-Expression reader can invoke
          itself without returning to the given number. The default limit
          is 1000. This limit applies to S-Expressions embedded within
          other S-Expressions as well as to S-Expressions that invoke
          recursive macros. If the limit is exceeded, Kermit prints
          "?S-Expression depth limit exceeded" and returns to its prompt.
          More about recursion in [497]Section 9.8.

   You can also test the depth programmatically:

   \v(sdepth)
          The current S-Expression invocation depth. The depth includes
          both nesting level and recursion. For example, in:
          (foo (foo (foo (foo (foo))))), the innermost (foo) is at depth
          5.

   Help, completion, and syntax checking are not available within an
   S-Expression. If you type ? within an S-Expression, it says:

  C-Kermit>(? S-Expression ("help sexp" for details)

   As it says, typing "help sexp" will display a brief help text.

   The SHOW SEXPRESSION command displays current SET SEXPRESSION settings
   and related information.

   [ [498]Top ] [ [499]Contents ] [ [500]C-Kermit Home ] [ [501]Kermit
   Home ]
     _________________________________________________________________

  9.4. Summary of Built-in Constants and Operators

   Three constants are built in:

     * PI, whose value is the value of pi (the quotient of circumference
       of any circle and its diameter, 3.141592653...) to the underlying
       machine's precision;
     * T, which always has the value 1, which signifies truth in Kermit
       logical expressions or S-Expressions;
     * NIL, which always has the empty value, and can serve as a False
       truth value.

   These constants are specific to S-Expressions and are not visible
   outside them. They may not be used as the target of an assignment. So,
   for example:

  (setq t 0)   Fails
  assign t 0   Succeeds but this is not the same T!

   E (the base of natural logarithms, 2.7182818184...) is not built in
   since it is not intrinsic in most Lisp dialects. If you want E to be
   the base of natural logarithms you can:

  (setq e (exp 1))

   Operators are either symbols (such as "+") or words. Words must be
   spelled out in full, not abbreviated. Differences of alphabetic case
   are ignored.

   The most basic operation in S-Expressions is evaluation:

   EVAL [ s-expression or variable or number [ another [ another ... ] ]
          ]
          Evaluates its operands and returns the value of the last one
          evaluated. Examples:

  (eval)                                0
  (eval 1)                              1
  (eval a)                              value of a
  (eval (+ 1 a))                        value of a+1
  (eval (setq a 1) (setq b (+ a 0.5)))  value of b (= a+0.5)

          You can use "." as a shorthand for EVAL:

  (.)
  (. 1)
  (. a)
  (. (+ 1 a))
  (. (setq a 1) (setq b (+ a 0.5)))

   Opposite of EVAL is the operator that suppresses evaluation of its
   operand:

   QUOTE item
          The value (quote item) is "item". If the item is itself an
          S-Expression, the result is the S-Expression with the outer
          parentheses stripped. Examples:

  (quote)                               (illegal)
  (quote a)                             a
  (quote hello)                         hello
  (quote (this is a string))            this is a string
  (quote this is a string)              (illegal)

          A shorthand notation is also accepted for quoting:
          'a is equivalent to (quote a). And therefore:
          '(a b c) is equivalent to (quote (a b c)).
          More about quoting in [502]Section 9.8.

   STRING item
          Is a combination of EVAL and QUOTE. It evaluates the item as an
          S-Expression, and then puts quotes around the result (more
          about this in [503]Section 9.8).

   The following operators assign values to variables:

   SETQ [ variable [ value [ variable [ value [ ... ] ] ] ] ]
          Applies to global variables. For each variable given: if a
          value is not given, the variable is undefined. If a value is
          given, assigns the value to the variable. The value may be a
          number, a variable, or anything that resolves to a number
          including an S-Expression. Returns the value of the last
          assignment. Examples:

  (setq)             Does nothing, returns NIL.
  (setq a)           Undefines a, returns NIL.
  (setq a 1)         Assigns 1 to a, returns 1.
  (setq a 1 b 2)     Assigns 1 to a, 2 to b, returns 2.
  (setq a 1 b 2 c)   Assigns 1 to a, 2 to b, undefines c, returns NIL.

   To undefine a variable that is not the final one in the list, give it
   a value of "()" or NIL:

  (setq a () b 2)    Undefines a, assigns 2 to b, returns 2.
  (setq a nil b 2)   Ditto.

   Note that a variable can be used right away once it has a value:

  (setq a 1 b a)     Assigns 1 to a, the value of a (1) to b, returns 1.

   The results of SETQ (when used with macro names) can be checked
   conveniently with SHOW MACRO, e.g:

  show mac a b c

   LET [ variable [ value [ variable [ value [ ... ] ] ] ] ]
          Like SETQ, but applies to local variables. Note that "local" is
          used in the Kermit sense, not the Lisp sense; it applies to the
          current Kermit command level, not to the current S-Expression.

   If you want to use SETQ or LET to assign a value to a backslash
   variable such as \%a or \&a[2], you must double the backslash:

  (setq \\%a 3)
  (setq \\%b (+ \%a 1))
  (setq \\&a[2] (setq (\\%c (+ \%a \%b))))

   In other words:

     * Double the backslash when you want to indicate the variable's
       NAME;
     * Don't double the backslash when you want its VALUE.

   See [504]Section 9.6 for a fuller explanation of variable syntax and
   scope.

   Here's a summary table of arithmetic operators; in the examples, a is
   2 and b is -1.3:

  Operator  Description                            Example           Result
  +         Adds all operands (0 or more)          (+ a b)           0.7
  -         Subtracts all operands (0 or more)     (- 9 5 2 1)       1
  *         Multiplies all operands (0 or more)    (* a (+ b 1) 3)  -1.80
  /         Divides all operands (2 or more)       (/ b a 2)        -0.325
  ^         Raise given number to given power      (^ 3 2)           9
  ++        Increments variables                   (++ a 1.2)        3.2
  --        Decrements variables                   (-- a)            1
  ABS       Absolute value of 1 operand            (abs (* a b 3))   7.8
  MAX       Maximum of all operands (1 or more)    (max 1 2 3 4)     4
  MIN       Minimum of all operands (1 or more)    (min 1 2 3 4)     1
  MOD (%)   Modulus of all operands (1 or more)    (mod 7 4 2)       1
  FLOAT     Convert an integer to floating-point   (float 1)         1.0
  TRUNCATE  Integer part of floating-point operand (truncate 3.333)  3
  CEILING   Ceiling of floating-point operand      (ceiling 1.25)    2
  FLOOR     Floor of floating-point operand        (floor 1.25)      1
  ROUND     Operand rounded to nearest integer     (round 1.75)      2
  SQRT      Square root of 1 operand               (sqrt 2)          1.414..
  EXP       e (2.71828..) to the given power       (exp -1)          0.367..
  SIN       Sine of angle-in-radians               (sin (/ pi 2))    1.0
  COS       Cosine of angle-in-radians             (cos pi)         -1.0
  TAN       Tangent of angle-in-radians            (tan pi)          0.0
  LOG       Natural log (base e) of given number   (log 2.7183)      1.000..
  LOG10     Log base 10 of given number            (log10 1000)      3.0

   The ++ and -- operators are also assignment operators and work just
   like SETQ and LET in their interpretations of operators and operands,
   but:

     * Each target variable must already be defined and have a numeric
       value;
     * The assignment value is the amount by which to increment or
       decrement the variable.
     * If an assignment value is not given, 1 is used.

   If you include more than one variable-value pair in a ++ or --
   expression, every variable (except, optionally, the last) must be
   followed by a value. Examples:

  (++ a)                Equivalent to (setq a (+ a 1)) and to (++ a 1)
  (++ a 2)              Equivalent to (setq a (+ a 2))
  (-- a (* 2 pi))       Equivalent to (setq a (- a (* 2 pi)))
  (++ a 1 b 1 c 1 d)    Equivalent to four SETQs incrementing a,b,c,d by 1.

   Another group of operators forms the predicates. These return a "truth
   value", in which 0 (or NIL) is false, and 1 or any other nonzero
   number is true.

  Operator  Description                            Example           Result
  = (or ==) Operands are equal                     (= 1 1.0)         1
  !=        Operands are not equal                 (!= 1 1.0)        0
  <         Operands in strictly ascending order   (< 1 2 3)         1
  <=        Operands in ascending order            (<= 1 1 2 3)      1
  >         Operands in strictly descending order  (> 3 2 1)         1
  >=        Operands in descending order           (<= 3 3 2 1)      1
  AND (&&)  Operands are all true                  (and 1 1 1 1 0)   0
  OR  (||)  At least one operand is true           (or 1 1 1 1 0)    1
  XOR       Logical Exclusive OR                   (xor 3 1)         0
  NOT (!)   Reverses truth value of operand        (not 3)           0

   The Exclusive OR of two values is true if one value is true and the
   other value is false.

   And another group operates on bits within an integer word:

  Operator  Description                            Example           Result
  &         Bitwise AND                            (& 7 2)           2
  |         Bitwise OR                             (| 1 2 3 4)       7
  #         Bitwise Exclusive OR                   (# 3 1)           2
  ~         Reverses all bits                      (~ 3)            -4

   These operators coerce their operands to integer by truncation if
   necessary. The result of bit reversal is hardware dependent.

   The final category of operator works on truth values:

  Operator  Description                            Example           Result
  IF        Conditional evaluation                 (if (1) 2 3)      2

   IF (predicate) (s1) [ (s2) ]
          The IF operator is similar to Kermit's IF command. If the
          predicate is true (i.e. evaluates to a nonzero number), the
          first S-Expression (s1) is evaluated and its value is returned.
          Otherwise, if (s2) is given, it is evaluated and its value
          returned; if (s2) is not given, nothing happens and the NIL
          (empty) value is returned.

   You can group multiple expressions in the s1 and s2 expressions using
   EVAL (or "."):

  (if (< a 0) (eval (setq x 0) (setq y 0)) (eval (setq x a) (setq y b)))

   or equivalently:

  (if (< a 0) (. (setq x 0) (setq y 0)) (. (setq x a) (setq y b)))

   Each operator has its own requirement as to number and type of
   operands. In the following table, "number" means any kind of number --
   integer or floating-point -- or a variable, function, macro, or
   S-Expression that returns a number; "vname" means variable name,
   "fpnumber" means a floating-point number (or anything that resolves to
   one), and "integer" means integer (or anything that resolves to one).
   "truthvalue" means anything that resolves to a value of zero or an
   empty value (which indicates false) or a nonzero value (which
   indicates true). "any" means any kind of value, including none at all.

  Operator  Number of operands   Type of operands    Returns
  EVAL  (.) 0 or more            S-Expression        Last value (default NIL)
  STRING    1                    S-Expression        string
  QUOTE (') 1                    word                string
  SETQ      0 or more            vname value pairs   Last value (default NIL)
  LET       0 or more            vname value pairs   Last value (default NIL)
  +         0 or more            number              number     (default 0)
  -         0 or more            number              number     (default 0)
  *         0 or more            number              number     (see note (1))
  /         2 or more            number              number
  ^         2 or more            number              number
  ++        1 or more            vname value pairs   Result of last increment
  --        1 or more            vname value pairs   Result of last decrement
  ABS       1                    number              number
  MAX       1 or more            number              number
  MIN       1 or more            number              number
  MOD (%)   2                    number              number
  FLOAT     1                    number              fpnumber
  TRUNCATE  1                    number              integer
  CEILING   1                    number              integer
  FLOOR     1                    number              integer
  ROUND     1                    number              integer
  SQRT      1                    number              fpnumber
  EXP       1                    number              fpnumber
  SIN       1                    number              fpnumber
  COS       1                    number              fpnumber
  TAN       1                    number              fpnumber
  LOG       1                    number              fpnumber
  LOG10     1                    number              fpnumber
  = (==)    1 or more            number              truthvalue
  !=        1 or more            number              truthvalue
  <         1 or more            number              truthvalue
  <=        1 or more            number              truthvalue
  >         1 or more            number              truthvalue
  >=        1 or more            number              truthvalue
  AND (&&)  1 or more            truthvalue          truthvalue
  OR  (||)  1 or more            truthvalue          truthvalue
  XOR       2                    truthvalue          truthvalue
  NOT (!)   1                    truthvalue          truthvalue
  &         1 or more            number (see note 2) integer
  |         1 or more            number (see note 2) integer
  #         2                    number (see note 2) integer
  ~         1                    number (see note 2) integer
  IF        2 or 3               truthvalue,any,any  any

   Operators that don't require any arguments return the default values
   shown.

    1. The value of "*", when used as an operator, is initially "1" and
       the value of the most recent S-Expression thereafter, as in Franz
       Lisp. This is handy when doing a series of calculations by hand:
  C-Kermit>(* 13272.42 0.40)
   5308.968
  C-Kermit>(/ * 2)
   2654.4840
  C-Kermit>
    2. The bitwise operators coerce their operands to integer by
       truncation.

   [ [505]Top ] [ [506]Contents ] [ [507]C-Kermit Home ] [ [508]Kermit
   Home ]
     _________________________________________________________________

  9.5. Variables

   As noted elsewhere in this discussion, all backslash items (variables
   such as \%a, macro parameters such as \%1, array elements such as
   \&a[\%i], built-in variables such as \v(ndate), built-in functions
   such as \fjoin(), macro names enclosed in \m(), \s(), or \:(), etc)
   are evaluated at "top level" before the S-Expression is sent to the
   S-Expression reader. To use a backslash variable as the target of an
   assignment (e.g. by SETQ, LET, ++, or --), you must double the
   backslash, e.g. (setq \\%r 1234). This is discussed at greater length
   in the next section.

   Thus S-Expression reader generally deals only with macro names (not
   backslash items) as variables. It is important to understand how the
   reader handles macro names. There are fundamentally two kinds of
   S-Expressions: those that contain a single element, such as:

  (foo)

   and those that contain more than one element:

  (foo a b c)

   If an S-Expression contains only one element, and it is the name of a
   macro, the macro's definition is examined. If the definition is a
   number (integer or floating-point, positive or negative), then this
   becomes the value of the expression. If the definition starts with '
   (apostrophe), then the quoted word or string is the value of the
   expression (explained in [509]Section 9.8). Otherwise, the macro is
   assumed to be composed of Kermit commands (possibly including
   S-Expressions), which are executed. If the macro has a RETURN value,
   or it executes an S-Expression as its last command, the result becomes
   the value of the S-Expression; otherwise the result is empty.

   For S-Expressions that contain more than one element, and the first
   element is the name of a macro, then this macro is executed with the
   arguments that are given, after the arguments are evaluated by the
   S-Expression reader. Likewise, If the first element is a built-in
   operator, then it is applied to the operands after they are evaluated.
   In both cases, each operand is fed to the S-Expression reader
   recursively for evaluation. If an operand is a number or a quoted
   string, it is used as-is. But if it's a macro name, this degenerates
   into the first case, and the previous paragraph applies.

   Examples:

  define foo 123
  (foo)                                Result: 123
  define foo 'abc
  (foo)                                Result: abc
  define foo '(one two three)
  (foo)                                Result: one two three
  define foo return \frandom(1000)
  (foo)                                Result: 713 (or other number)
  define foo (+ a b)
  (foo)                                Result: The sum of a and b

   A more difficult example:

  define foo abc
  (foo)                                Result: ???

   The result in the last example depends on the definition of abc:

     * If it has no definition, an error occurs; otherwise:
     * If the definition is an S-Expression, the result is the
       S-Expression's value; otherwise:
     * If the definition consists of Kermit commands, they are executed.
       But in this case "(foo)" produces the empty result, because it
       doesn't RETURN anything.

   The use of macros as S-Expression operators is described in
   [510]Section 9.8.

   [ [511]Top ] [ [512]Contents ] [ [513]C-Kermit Home ] [ [514]Kermit
   Home ]
     _________________________________________________________________

  9.6. Assignments and Scope

   The assignment operators SETQ and LET apply to global and local
   variables, respectively. SETQ and LET are standard Lisp operators
   adapted to Kermit scoping rules. When the operands are numeric or
   arithmetic, SETQ is equivalent to Kermit's EVALUATE command:

  (setq a (+ 1 2))
  evaluate a 1 + 2

   When the operand is a string, SETQ is equivalent to DEFINE:

  (setq a '(this is a string))
  define a this is a string

   In the first case, both statements create a macro named "a" with a
   value of 3. But in neither case is the macro "a" necessarily global.
   If either of these commands executes in an environment (i.e. macro
   invocation level) where a "local a" command has been given, the "a"
   macro is global to that environment, but is not visible outside it.

   LET is equivalent to the Kermit LOCAL command, followed by the
   corresponding EVALUATE:

  (let a (+ 1 2))

   is equivalent to:

  local a
  evaluate a 1 + 2

   Again, "local" in this context applies to the Kermit macro invocation
   stack, not to the S-Expression nesting level. To illustrate, recall
   our "newarea" macro:

def newarea {
    (let a \%1 b \%2 c \%3)
    (let s (/ (+ a b c) 2.0))
    (sqrt (* s (- s a) (- s b) (- s c)))
}

   Because SETQ and LET expressions return a value, they can be placed
   within a larger S-Expression. In this case we can replace the first
   reference to the "s" variable by its defining expression:

def newarea {
    (let a \%1 b \%2 c \%3)
    (sqrt (* (let s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c)))
}

   This would not work if LET were local to the S-Expression, but it
   works nicely in the context of Kermit macros. The previous definition
   is equivalent to:

def newarea {
    local a b c s
    (setq a \%1 b \%2 c \%3)
    (sqrt (* (setq s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c)))
}

   In both cases, the variables a, b, c, and s are local to the "newarea"
   macro, and global within it.

   Multiple assignments can be handled in several ways. Here is the
   obvious way to initialize a series of variables to the same value:

  (setq a 0)
  (setq b 0)
  (setq c 0)
  (setq s 0)

   Here is a more compact and efficient way of doing the same thing:

  (setq a 0 b 0 c 0 s 0)

   However, in case the value was more complex, it's better to put only
   one copy of it in the S-Expression; in this case we rely on the fact
   that SETQ returns the value of its last assignment:

  (setq a (setq b (setq c (setq s (* x (^ y 2))))))

   Similarly, to set a series of variables to x, x+1, x+2, ...

  (setq c (+ (setq b (+ (setq a (+ (setq s x) 1)) 1)) 1))

   In the last example, you can see why "last" does not always correspond
   to "rightmost" (the leftmost variable "c" is assigned last).

   If you are working with backslash variables like \%a or array elements
   like \&a[1], remember two rules:
    1. Don't put spaces inside array brackets.
    2. You must double the backslash when using SETQ, LET, ++, or -- to
       assign a value to a backslash variable.

   Examples of assigning to a backslash variable:

  (setq x 1)
  (setq \\%a 0)
  (setq \\&a[x+1] 1)
  (++ \\%x)
  (-- \\&a[x+2])

   Examples of referring to a backslash variable's value:

  (setq a (+ \%a 1))
  (setq b (+ \%a \&a[1]))
  (++ a \%x)
  (-- b \&a[1])

   The special notation is required because all backslashed items (\%x
   variables, array elements, built-in \v(xxx) variables, and \fxxx()
   function invocations) are evaluated in a single pass BEFORE the
   S-Expression is executed; any other approach would result in
   unacceptable performance. So, for example, in:

  declare \&a[] = 1 2 3
  define \%x 4
  define \%y 0
  (setq \\%y (+ \%x \&a[1]))

   the S-Expression becomes:

  (setq \%y (+ 4 1))

   before it is sent to the S-Expression evaluator. If the backslash had
   not been doubled on the assignment target, the result would have been:

  (setq 0 (+ 4 1))

   which is illegal because you can't assign a value to a number.
   Conversely, if backslashes were doubled on right-hand-side values:

  (setq \\%y (+ \\%x \\&a[1])

   this too, would give an error (not numeric - "\%x").

   If you omit the double backslash in the assignment target, the result
   depends on whether the variable already has a value:

  (setq \%a (* 3 3))

   If \%a has a non-numeric single-word value, then this becomes the name
   of the variable that is assigned by SETQ. To illustrate:

  define \%a foo
  echo \%a
  foo
  (setq \%a (* 3 3))
  echo \%a
  foo
  show macro foo
  foo = 9

   If \%a has no value, a numeric value, or a multiword value, an
   "invalid assignment" error occurs.

   [ [515]Top ] [ [516]Contents ] [ [517]C-Kermit Home ] [ [518]Kermit
   Home ]
     _________________________________________________________________

  9.7. Conditional Expressions

   The IF operator provides a compact form of decision-making within
   S-Expressions. An IF expression can stand wherever a number might
   stand, as long is it returns a number. Here's a quick way to obtain
   the average value of all the elements in an array that contains only
   numbers:

  (/ (+ \fjoin(&a)) (float \fdim(&a)))

   This results in a "Divide by zero" error if the array is empty. If you
   want to define the average value of an empty array to be 0 instead of
   getting an error, you can use IF to check the array size:

  (if \fdim(&a) (/ (+ \fjoin(&a)) (float \fdim(&a))) 0)

   or equivalently:

  (if (not \fdim(&a)) 0 (/ (+ \fjoin(&a)) (float \fdim(&a))))

   Of course, IF can fit anywhere else into an S-Expression:

  (setq a (+ b (if (< c 0) 0 c)))

   and the IF expression can be as complex as you like:

  (setq a (+ b (if (and (or (> x 0) (> y 0)) (< c 0) (> d 1) (!= e 0)) 1 0)))

   and the "then" and "else" parts can contain multiple S-Expressions
   enclosed within (EVAL ...):

  (if x (eval (...) (...) (...)) (eval (...) (...) (...)))

   AND and OR operators are guaranteed to "short circuit". If any operand
   of AND is false, none of the subsequent operands is evaluated;
   likewise, if an OR operand is true, no further operands are evaluated.

   Bear in mind that the S-Expression IF is not the same as Kermit IF;
   the condition is only allowed to be an S-Expression or a variable or
   number, not the whole list of possibilities you see when you type "if
   ?" at the C-Kermit> prompt. But keep reading...

   [ [519]Top ] [ [520]Contents ] [ [521]C-Kermit Home ] [ [522]Kermit
   Home ]
     _________________________________________________________________

  9.8. Extensibility

   To extend the capabilities of S-Expressions, you can use Kermit macro
   names as operators, with the following limitations:

     * The macro must not have the same name as a built-in operator.
     * You must use the full macro name, not an abbreviation.

   And with the following enhancement:

     * If the last statement executed by the macro is an S-Expression,
       its value is returned automatically. In other words:

  define bump (++ \%1)

   is equivalent to:

  define bump return \fsexpression(++ \%1)

   Here's an example in which we define a FIBONACCI operator that returns
   the nth element, n >= 0, of the Fibonacci series, 0 1 1 2 3 5 8 13 21
   34 55, . . ., in which the first element is 0, the second is 1, and
   each subsequent element is the sum of the two before it. This series
   was devised by Leonardo Pisano, Filius Bonacci (Fibonacci for short)
   in 1202 to describe how fast rabbits can breed, and also forms the
   basis for the Golden Mean, the branching behavior of plants, the
   spiral of a nautilus shell, etc. (Thanks to [523]Dat Thuc Nguyen for
   December 2003 corrections to this section!)

   We can write a FIBONACCI function as a macro easily with
   S-Expressions:

  define FIBONACCI {
    (if (== \%1 0) 0
        (if (== \%1 1) 1 (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1)))))
  }

   You can read this as:

     If the argument (\%1) is 0, return a result of 0; if it is 1,
     return 1; otherwise:
     return the sum of fibonacci(argument - 2) and fibonacci(argument -
     1)

   Note that a RETURN statement is not needed, since S-Expressions
   automatically set the return value of their containing macros.

   For comparison, here's how it would be coded without S-Expressions:

  define FIBONACCI {
      if == \%1 0 {
          return 0
      } else if == \%1 1 {
          return 1
      } else {
          return \feval(\fexec(fibonacci \feval(\%1-2)) -
               + \fexec(fibonacci \feval(\%1-1)))
      }
  }

   Now we can use the FIBONACCI function (whichever way you write it)
   just as if it were a built-in operator:

  (fibonacci 6)

   Or:

  (setq a 10)
  (fibonacci a)

   Within S-Expressions only (not outside them), S-Expressions themselves
   can be used as macro arguments:

  (setq a 2 b 4)
  (setq x (fibonacci (* a b )))

   The value of the S-Expression (in this case "8"), and not the
   S-Expression itself, is sent to the macro.

   Your macro is responsible for argument validation and error handling.
   A robust Fibonacci macro would be more like this:

  define FIBONACCI {
      if < \v(argc) 2 end 1 ?\%0: Missing argument
      if > \v(argc) 2 end 1 ?\%0: Too many arguments
      if not integer \%1 end 1 ?\%0: Integers only
      if < \%1 1 end 1 ?\%0: Argument out of range
      (if (== \%1 0) 0
         (if (== \%1 1) 1 (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1)))))
  }

   Recall that "END nonzero-number [ message ]" causes a macro invocation
   to fail. When the macro is the operator in an S-Expression, this makes
   the S-Expression fail too. Also note that our Fibonacci macro is just
   an illustration, not a practical example. Since it is recursive (calls
   itself), it won't work for large arguments because the call stack can
   exceed available memory. See [524]Section 9.9.2 for a practical
   alternative.

   Kermit macros, when used as S-Expression operators, can do anything at
   all except initiate file transfers: they can print messages on the
   screen, read and write files, interact with the user, and so on. For
   example, here's a macro ASKME that asks you to enter a number, makes
   sure that you did, and then returns its value for use in the
   S-Expression:

  define ASKME {
      local \%n
      while true {
          ask \%n { Number: }
          if not def \%n continue
          if not numeric \%n {
              echo Not numeric - "\%n"
              continue
          }
          break
      }
      return \%n
  }
  (setq a (* 2 (askme))) ; Get number from user, double it, assign result to a.

   Here's a macro you can use to validate that a number is in a given
   range:

  define inrange {
      if != \v(argc) 4 end 1 ?\%0: Wrong number of arguments
      if ( < \%1 \%2 || > \%1 \%3 ) return 0
      return 1
  }

   The first argument is the number to be checked, the second is the
   minimum acceptable value, the third is the maximum. You can use this
   (for example) in IF conditions:

  define yes echo \%1 IS OK
  define no echo \%1 IS NOT OK

  (setq a -1 b 999)
  (if (inrange a 0 100) (yes a) (no a))
  (if (inrange b -1000 +1000) (yes b) (no b))

   This is just an illustration, of course; there's already a built-in
   operator to let you do range checking without help from macros:

  (if (<= 0 a 100) (yes a) (no a))
  (if (<= -1000 b +1000) (yes b) (no b))

   To send string parameters to a macro, some kind of quoting is required
   to tell the S-Expression parser to take a given "word" literally
   rather than replacing it by its value. For this we use the Lisp QUOTE
   operator:

  define length return \flength(\%1)
  (length (quote abcdefghijklmnopqrstuvwxyz))
  26

   This causes the string "abcdefghijklmnopqrstuvwxyz" to be sent
   literally to the LENGTH macro. Kermit, like Lisp, also offers a
   shortcut for QUOTE, that lets us quote a word by prefixing it with a
   single quote (') character, also called apostophe (ASCII 39):

  (length 'abcdefghijklmnopqrstuvwxyz)
  26

   The two forms are equivalent.

   How the macro treats its arguments is up to the macro. In the example
   above, the argument is treated as a literal string. However, it can
   also be treated as a variable name:

  define string This is a string
  define length return \flength(\m(\%1))
  (length 'string)
  16

   Note the construct \m(\%1). This means "the value of the macro whose
   name is the value of
   \%1". The value of \%1 in this case is the word "string", and the
   value of the macro whose name is "string" is "This is a string".

   What if the macro takes multiple arguments, or a variable number of
   them? Here's a simple macro that prints a phrase that includes its
   arguments:

  define complain echo It's too \%*!

   (Recall that \%* means "all arguments".)

   It can be called in the traditional way:

  complain hot                       Result: "It's too hot!"
  complain cold and wet              Result: "It's too cold and wet!"

   Or from an S-Expression if you quote the arguments:

  (complain 'hot)                    Result: "It's too hot!"
  (complain 'cold 'and 'wet)         Result: "It's too cold and wet!"

   To group multiple words into a single argument, use parentheses:

  (complain (quote (cold and wet)))  Result: "It's too cold and wet!"
  (complain '(cold and wet))         Result: "It's too cold and wet!"

   Note the difference:

  (complain 'cold 'and 'wet)         Three arguments
  (complain '(cold and wet))         One argument

   Since the COMPLAIN macro uses \%* to refer to all its arguments, no
   matter how many, it doesn't care which form you use. But it makes a
   difference in cases where the macro refers to its arguments
   individually.

   To illustrate, let's consider a macro that receives the name of a
   macro and its argument list and executes it with its arguments,
   without knowing how many arguments there are. The following LOOP macro
   is used to execute the given macro with the given argument list the
   requested number of times:

  def loop { local i, for i 1 \%1 1 do \%2 \%3 }

   Within the LOOP macro, the first argument (\%1) is the loop count, \%2
   is the macro name, and \%3 is the argument list. When the LOOP macro
   is invoked traditionally like this:

  loop 3 complain hot

   it prints "It's too hot!" three times. To invoke it from an
   S-Expression, you must quote both the macro name as well as the
   argument, since in this case the macro name itself is an argument:

  (loop 3 'complain 'hot)

   Now what if you need to send different or variable numbers of
   arguments to the LOOP macro? The LOOP macro can handle it already,
   provided you group the arguments into LOOP's third argument (\%3). In
   Kermit syntax, without grouping:

  loop 3 complain cold and wet

   prints "It's too cold!" three times ("and wet" is lost); but with
   grouping (either of the following two forms):

  loop 3 complain {cold and wet}
  loop 3 complain "cold and wet"

   the LOOP macro prints "It's too cold and wet!" three times as desired.

   To do the same thing in an S-Expression, just use the Lisp forms of
   quoting instead of the Kermit forms; the following two are equivalent:

  (loop 3 'complain (quote (cold and wet)))
  (loop 3 'complain '(cold and wet))

   Here's a similar example in which we write a macro that shows both the
   name and the value of one or more other macros, whose names are given
   as arguments (similar to "show macro"):

  define display {
      local \%i
      for \%i 1 \v(argc)-1 1 {
          echo \&_[\%i] = \m(\&_[\%i])
      }
  }

   (Recall that \&_[] is the macro's argument vector array, equivalent to
   \%1, \%2, ...) The DISPLAY macro can be used in S-Expressions like
   this:

  (setq a 1 b 2 c 3)
  (display 'a 'b 'c 'd)

   which prints:

  a = 1
  b = 2
  c = 3
  d =

   The names must be quoted to prevent their evaluation before they are
   sent to the macro. This ability to pass variables "by name" to macros,
   rather than by value, lets you write macros that change the values of
   argument variables. For example, here's a macro that doubles the value
   of its argument variable:

  define double (++ \%1 \%1)

   which you can call like this:

  (setq a 12)
  (double 'a)

   In the macro, \%1 is replace by the variable name "a"; "(++ a a)" adds
   "a" to itself, and sets the value of "a" to the result.

   There are no built-in operators other than QUOTE, ', and STRING for
   handling strings in S-Expressions, but using just these, plus macros
   that use Kermit's regular string-handling features, you can easily
   extend S-Expressions to do string manipulation:

  define len return \flen(\%1)               Returns length of argument string
  define cap return \fupper(\%1)             Uppercase argument string
  define rev return \freverse(\%1)           Reverses argument string
  define sub return \fsubstr(\%1,\%2,\%3)    Returns substring of arg string

  (len '(this is a string))                  Result: 16
  (rev '(this is a string))                  Result: gnirts a si siht
  (rev (cap '(this is a string)))            Result: GNIRTS A SI SIHT
  (sub (rev (cap '(this is a string))) 5 9)  Result: TS A SI S

   You can assign a string to a macro name as follows:

  (setq foo '(this is a string))
  (setq foo (quote (this is a string)))

   The two are exactly equivalent. In both cases, the macro "foo" has the
   value:

  '(this is a string)

   so when it is retrieved it can be identified as a string rather than a
   number or commands to be executed. Thus:

  (setq foo (quote (this is a string)))
  show macro foo
  foo = '(this is a string)
  (foo)
  this is a string

   Note the different results for "show macro foo" and "(foo)". The
   former shows the internal definition; the latter evaluates the
   variable, which removes the quoting. And perhaps more important, note
   that if the apostrophe and surrounding parentheses were not stored as
   part of the definition, (foo) would try to execute "this is a string"
   as a command.

   Given the assignment above, the following work as expected:

  (len foo)                                  Result: 16
  (rev foo)                                  Result: gnirts a si siht
  (rev (cap foo))                            Result: GNIRTS A SI SIHT
  (sub (rev (cap foo)) 5 8)                  Result: TS A SI S

   Note that, unlike built-in S-Expression operators that return numbers
   or truth values, these operators return strings. If you want to assign
   their return values to other variables, you can do so:

  (setq bar (rev (cap foo)))                 Result: GNIRTS A SI SIHT

   But now the S-Expression processor doesn't know the value of "bar" is
   supposed to be a string, rather than a macro to execute. For this you
   need one final special operator, STRING. The STRING operator takes an
   S-Expression as an operand, evaluates it, and then returns its value
   enclosed in '(), so you can use the value as a string is subsequent
   S-Expressions. Use STRING for referencing macros that return strings:

  (setq bar (string (rev (cap foo))))        Result: '(GNIRTS A SI SIHT)

   STRING is like QUOTE, except that it evaluates its operand before
   applying the quoting, rather than taking the operand literally.

   To reference backslash variables or functions that return string
   values, you must use the regular quoting mechanisms:

  (setq time '(\v(time)))
  (setq date '(\v(date)))
  assign \%r this is a string
  (setq s1 '(\%r))

   That's because backslash items are evaluated BEFORE the S-Expression
   parser ever sees them, and the values of \v(time) and so on are not
   valid S-Expressions, so STRING won't like them.

   Finally a brief word on the touchy topic of quoting. Suppose you want
   to include (say) literal parentheses in a string that will later be
   processed by the S-Expression reader (or \fsplit() or \fword()).
   Normally, you can't do this because parentheses are meaningful in
   these contexts. To defeat the normal parsing rules, you can quote the
   parentheses with backslash. However, due to the many levels of string
   processing involved, a surprisingly large amount of backslashes might
   be required, for example:

  (setq s '(a b (c d) \\\\\\\\\\\\\\\\(e f (g h) x\\\\\\\\\\\\\\\\) j k))

   This is nearly impossible to explain(*). Instead, just remember two
   points:

     * In situations like this, it's better to use DEFINE to create the
       string, rather than SETQ. The example above requires only double
       backslashes when DEFINE is used:
  define s '(a b (c d) \\(e f (g h) x\\) j k)
     * The level of quoting depends on how many levels of evaluation the
       string must pass through, which is not always obvious. However,
       the number of backslashes required in any given situation is
       always a power of 2. So if 1 doesn't work, try 2; if 2 doesn't
       work, try 4; if 4 doesn't work, try 8, 16, 32, and so on.

   Considerations like this apply in any scripting language (shell, Tcl,
   Perl, Python, etc). The situation is known as "Quoting Hell".

   (*) If you really want an explanation, here it is:

     * Every SEXP has its backslash items evaluated in a single pass at
       top level before being passed to the SEXP reader, so \%1,
       \v(ftime), etc, can be evaluated up front, freeing the SEXP reader
       of having to know about such things, which in turn makes it much
       more efficient. Therefore one level of quoting is lost right away,
       and therefore you must double each backslash that is to be used as
       a quote.
     * When the SEXP reader sees '\', it treats it as a quote; discards
       it and keeps the next character. Thus '\\' becomes '\'. This would
       be the end of it, except that:
     * The SEXP reader must call itself recursively on its operands, so
       we must double any quotes in the operands: 2^2 = 4.
     * If the result is to be passed as an argument to a macro, the
       backslashes must again be doubled, because the macro processor
       evaluates the arguments before sending them to the macro: 2^3 = 8.
     * If the macro itself is to see the quotes, rather than just the
       result of the quoting, the quotes must be doubled again: 2^4 = 16.

   Moral: To create string constants in which grouping characters must be
   quoted, use DEFINE rather than SETQ.

   [ [525]Top ] [ [526]Contents ] [ [527]C-Kermit Home ] [ [528]Kermit
   Home ]
     _________________________________________________________________

  9.9. Examples

    9.9.1. Statistics

   The following program computes statistics -- means, maxima, mimima,
   variance, standard deviation, and correlation -- from data stored in
   parallel arrays, \&x[] and \&y[], which can contain any mixture of
   integer and floating-point numbers: positive, negative, or zero. Array
   setup and validation are not shown. Except for the traditional FOR
   loop and printing the results at the end, the entire computation is
   done with S-Expressions:

; Initialize sums, maxima, minima, and number of elements

  (setq xsum 0 ysum 0 xsum2 0 ysum2 0 xysum 0)
  (setq xmin (setq xmax \&x[1]) ymin (setq ymax \&y[1]))
  (setq n \fdim(&x))

; Loop through elements and accumulate sums, maxima, and minima

  for i 1 n 1 {
      (setq x \&x[i] y \&y[i])                    ; Notational convenience
      (setq xmax (max xmax x) ymax (max ymax y))  ; X and Y maxima
      (setq xmin (min xmin x) ymin (min ymin y))  ; X and Y minima
      (++ xsum x ysum y)                          ; X and Y sums
      (++ xsum2 (^ x 2) ysum2 (^ y 2))            ; Sum of X and Y squares
      (++ xysum (* x y))                          ; Sum of XY products
  }

; Calculate results

  (setq xmean (/ xsum n) ymean (/ ysum n))        ; Mean X and Y
  (setq xss (- xsum2 (/ (^ xsum 2) n)))           ; Intermediate values
  (setq yss (- ysum2 (/ (^ ysum 2) n)))
  (setq xyss (- xysum (/ (* xsum ysum) n)))
  (setq xvar (/ xss n) yvar (/ yss n))            ; X and Y variance
  (setq sdx (sqrt xvar) sdy (sqrt yvar))          ; Std deviation in X and Y
  (setq tmp (* xss yss))
  (setq cc (if tmp (/ xyss (sqrt tmp)) 1.0))      ; Correlation coefficient
  show macro xmean ymean xvar yvar sdx sdy cc     ; Print the results

   The final "if tmp" check accounts for the possibility that both arrays
   contain all 0's. Results can also be printed with "echo CC = \m(cc)",
   or any other desired way. Interestingly, if we had not needed the sum
   of the squares and products, we could have obtained the sums, maxima,
   and minima of the X's and Y's without a loop like this:

  (setq xsum (+ \fjoin(&x)) ysum (+ \fjoin(&y)))
  (setq xmax (max \fjoin(&x)) ymax (max \fjoin(&y)))
  (setq xmin (min \fjoin(&x)) ymin (min \fjoin(&y)))

   Any Kermit function that returns numbers or lists of numbers can be
   included in an S-Expression as an operand.
     _________________________________________________________________

    9.9.2. Practical Fibonacci Series

   The recursive Fibonacci example given previously is simple and
   elegant, but not very useful since it causes memory occupation to grow
   each time it calls itself, until eventually both physical memory and
   disk swap space are filled and the program crashes. Even for small
   arguments, like 17, execution time can be prohibitive:

  (setq t1 \v(ftime))
  (setq result (fibonacci 17))
  (setq t2 (- \v(ftime) t1))
  echo FIBONACCI(17) = \m(result): TIME = \ffpround(t2,3)

   prints (on a certain rather slow computer):

  FIBONACCI(17) = 1597: TIME = 5.861

   Any recursive function can be recoded iteratively. The result is not
   as pretty, but execution is far less expensive:

    define FIBITER {
        (if (== \%3 0) (\%2) (fibiter (+ \%1 \%2) \%1 (- \%3 1)))
    }
    define FIBONACCI {
        (fibiter 1 0 \%1)
    }

   Here's the result on the same computer for the same argument of 17:

  FIBONACCI(17) = 1597: TIME = 0.015

   (47 times faster.) Execution time increases proportionally to the size
   of the argument in the iterative case, whereas in the recursive case
   it goes up geometrically, quickly reaching infinity.

   [ [529]Top ] [ [530]Contents ] [ [531]C-Kermit Home ] [ [532]Kermit
   Home ]
     _________________________________________________________________

  9.10. Differences from Algebraic Notation

   In C-Kermit:

     * Algebraic notation uses infix operators and normal rules of
       operator precedence, with parentheses used to force exceptions to
       the rules; many operations can be included in an expression.
       S-Expressions use prefix operators with no intrinsic precedence;
       each operation is enclosed in parentheses, and the arrangement of
       parentheses determines precedence.
     * Algebraic infix operators require two operands; S-Expression
       prefix operators can accept a variable number of operands.
     * You can use algebraic notation anywhere that C-Kermit accepts a
       number, e.g. "echo \&a[((1+1)*2-1]", but you can use S-Expressions
       only as top-level commands. You can, however, use either algebraic
       or S-Expressions anywhere at all by enclosing them in \fevaluate()
       or \fsexpression(), respectively.
     * You can use any mixture of integer and floating-point numbers in
       S-Expressions, but only integers are permitted in algebraic
       expressions. Outside of S-Expressions, floating point arithmetic
       is supported only by \ffp...() function calls.
     * Operators and operands in S-Expressions must be separated by
       spaces, e.g. "(+ a b)". Spaces are not required in algebraic
       expressions: "((a+b)*c)".
     * When assigning values to backslash variables (such as \%x or
       \&a[2]) using SETQ or LET, you must double the backslash.

   [ [533]Top ] [ [534]Contents ] [ [535]C-Kermit Home ] [ [536]Kermit
   Home ]
     _________________________________________________________________

  9.11. Differences from Lisp

     * Kermit has a lot of built-in operators not found in Lisp: ++, ^,
       etc.
     * Most dialects of real Lisp do not allow S-Expressions that don't
       start with an operator, for example:
  (a)
       This expression can cause an error in Lisp (even if "a" has a
       value), but is acceptable in Kermit, where it returns the value of
       the variable "a". Similarly, (1) returns the value "1".
     * In real Lisp, EVAL requires exactly one operand. In Kermit, it can
       have 0, 1, 2, or more operands. It returns the value of the last
       operand evaluated.
     * Real Lisp SETQ and LET usually require an even number of operands.
       Kermit allows an odd number, in which case the last (or only)
       variable is undefined (i.e. deleted, destroyed).
     * Kermit does not support ratios such as "7/8". Some Lisp dialects
       accept ratios as numbers, and generate ratios when told to divide
       two integers whose quotient is not a whole number; e.g. in Common
       Lisp:
  [13] USER(37): (/ (+ 1 2 3 4) 3)
  10/3
  [13] USER(38):
     * The result of (/ 10 3) is 3.333.... Some Lisp dialects truncate
       the result to 3 since both operands are integers, some don't; some
       give the result as a ratio. C-Kermit always gives a floating point
       result when there is a fractional part. If you want an integer
       result, you can use TRUNCATE, FLOOR, or CEILING, e.g. (truncate (/
       10 3)).
     * There is currently no "bignum" support. Large numbers can be used
       and large results generated, but (as noted in [537]Section 9.2)
       they are accurate only to the precision of the underlying machine.
       \v(math_precision) gives the machine precision as a number of
       decimal digits, e.g. 16.
     * Scientific notation for floating-point numbers is not supported.
       If the magnitude of a number is greater than the precision of the
       underlying hardware, the less-significant digits are shown but
       their values are meaningless. If it the number is too small to be
       represented internally, it is shown as "0.0".
     * Many Lisp features are omitted: List processing (CAR, CDR, etc),
       DEFUN, Lisp-specific control structures, and so on.

   [ [538]Top ] [ [539]Contents ] [ [540]C-Kermit Home ] [ [541]Kermit
   Home ]
  __________________________________________________________________________

10. FILE TRANSFER

   New commands and switches:

   SET TRANSFER REPORT { OFF, ON }
          Enables or disables the (new) one-line message printed by
          Kermit after a remote-mode file transfer to indicate the source
          and destination file, complete with path, to let you know where
          the file went.

   SEND /TYPE:{TEXT,BINARY}
          Sends only files of the given type (see [542]Section 4).

   SEND /NOFOLLOWLINKS:
          (UNIX only) Skip over symbolic links rather than following them
          (default). This applies to wildcard and/or recursive SENDs; if
          a single filename is given, and it happens to be a symbolic
          link, the file it points to is sent.

   SEND /FOLLOWLINKS:
          (UNIX only) Follow (resolve) symbolic links. Watch out for
          circular links, endless loops, etc.

   SET SEND I-PACKETS { OFF, ON }
          When sending commands to a Kermit server, this tells whether
          command packets should be preceded by an I (information)
          packet, which is used to synchronize parameters prior to
          executing the command. Normally ON. The only reason to set this
          OFF is for communicating with buggy Kermit servers that
          misbehave when an I packet is sent to them. There is also a SET
          RECEIVE I-PACKETS command, but presently it has no effect.

   SET TRANSFER MESSAGE [ text ]
          Sets an initial message to be shown in the Last Message field
          of the fullscreen file-transfer display.

   SET TRANSFER TRANSLATION { ON, OFF }
          Inhibits or re-enables text-file transfer character-set
          translation globally.

   { SEND, MSEND, GET, RECEIVE } /TRANSPARENT
          Inhibits character-set translation for this transfer only.

   { GET, RECEIVE } /PIPES:{ON,OFF}
          Overrides global TRANSFER PIPES setting for this transfer only;
          ON allows incoming files with names like "!tar xf -" to be
          opened as pipelines rather than regular files.

   The following new "hot keys" are available when Kermit's file-transfer
   display is visible:

     D: Turn on debugging, open "debug.log" if not already open.
     d: Turn off debugging but leave log open (if it was open).
     T: Turn on debug-log timestamps.
     t: Turn off debug-log timestamps.

   Other improvements:
     * SET FILE DOWNLOAD-DIRECTORY now works for external protocols (e.g.
       sz/rz) too.
     * Improved automatic per-file text/binary switching, described in
       [543]Section 4.
     * When sending a file group (e.g. "send *.*"), failure to open a
       file is no longer fatal; now C-Kermit simply goes ahead to the
       next file.
     * Transaction log entries are now made for external protocols too.

   [ [544]Top ] [ [545]Contents ] [ [546]C-Kermit Home ] [ [547]Kermit
   Home ]
  __________________________________________________________________________

11. MODEMS AND DIALING

   In C-Kermit 8.0, the default modem type for dialing has changed from
   NONE (= DIRECT, meaning no modem) to GENERIC. This change should have
   no impact on direct connections. For dialing, it means that, unless
   you SET MODEM TYPE to a specific type, such as USROBOTICS or CONEXANT,
   Kermit assumes:

    1. The modem uses the Hayes AT command set.
    2. The modem supports error correction, data compression, and
       hardware flow control and is already configured to use them.

   In fact, Kermit assumes the modem is completely configured, and
   therefore does not send it an initialization string or any
   configuration commands. Instead, it sends only the simplest and most
   portable commands:

     ATQ0V1          Give dial result codes.
     ATDTnumber      Dial the number.

   (or ATD or ATDP, as appropriate).

   The new defaults work for direct connections and for most modern
   modems on most platforms, and they work much faster than
   "full-treatment" dialing. If the new defaults don't work for you, or
   if you need to perform explicit modem configuations or interactions,
   then set a specific modem type and use the SET MODEM and SET DIAL
   commands as documented in Using C-Kermit.

     WARNING: Don't use the generic modem on hosts that do not support
     RTS/CTS flow control. If Xon/Xoff is in use on the serial port,
     you'll need to select a particular modem type so Kermit knows what
     command to give it to enable Xon/Xoff flow control between itself
     and your serial port.

   The following new modem types were added in C-Kermit 8.0:

     lucent:          Lucent Venus chipset
     pctel:           PCTel V.90 chipset
     conexant:        Conexant (ex-Rockwell) modem family
     zoom-v32bis:     New name for "Zoom"
     zoom-v34         Zoom V.34
     zoom-v90         Zoom V.90 56K
     zoom-v92:        Zoom V.92 with V.44 data compression
     zoltrix-v34:     New name for "zoltrix"
     zoltrix-hsp-v90: Synonym for PCTel
     zoltrix-hcf-v90: Synonym for ITU-T-V250
     smartlink-v90:   Synonym for usrobotics (same chipset)
     acer-v90:        Synonym for Rockwell-v90

   New DIAL-related variables:

     \v(dm_hf):  Dial modifier: Wait for Hook-Flash.
     \v(dm_wb):  Dial modifier: Wait for Bong.

   Finally, if dialing fails, Kermit now prints a context-sensitive hint
   suggesting possible reasons and remedies.

   Added in C-Kermit 8.0.201:   Rudimentary support for Caller ID, for
   use with the ANSWER command. If the modem reports Caller ID
   information, Kermit stores it in variables that you can access after
   the call is answered:

  \v(callid_date)   The date of the call
  \v(callid_time)   The time of the call
  \v(callid_name)   The name of the caller
  \v(callid_nmbr)   The telephone number of the caller
  \v(callid_mesg)   A message

   The format of these items depends on the originating and answering
   phone companies and the modems and their configuration.

   Not very many modems support Caller ID, and those that do (a) tend to
   have it disabled by default, and (b) use different commands to enable
   it. A quick survey shows of some current models shows:

   - USR V.90:      No
   - ITU-T V.250:   No
   - Lucent Venus:  No
   - Diamond Supra: #CID=1
   - Rockwell 56K:  #CID=1
   - PCTEL:         #CID=1
   - Zoltrix:       +VCID=1
   - Conexant:      +VCID=1

   To use Kermit's Caller ID feature, you have to set the modem to wait
   for at least two rings before answering, and you have to give the
   command to enable Caller ID; for example (after choosing a modem with
   SET MODEM TYPE):

  set modem command autoanswer on ATS0=2#CID=1\{13}
  set modem command autoanswer on ATS0=2+VCID=1\{13}

   These commands can be undone with:

  set modem command autoanswer on ATS0=1#CID=0\{13}
  set modem command autoanswer on ATS0=1+VCID=0\{13}

   Kermit presently has no built-in knowledge of the Caller ID
   capabilities or commands of the modems in its database.

   Since the variables can be accessed only after the call is answered,
   the only way to refuse a call is to answer it, inspect the variables,
   and then hang it up if desired.

   [ [548]Top ] [ [549]Contents ] [ [550]C-Kermit Home ] [ [551]Kermit
   Home ]
  __________________________________________________________________________

12. TERMINAL CONNECTION

   Now that 7-bit connections are no longer the norm, the default
   terminal bytesize (also called "data size" or "word size") in C-Kermit
   8.0 is 8 bits, rather than 7 bits as it was in C-Kermit 7.0 and
   earlier:

   SET ESCAPE character
          This command, which specifies your CONNECT-mode escape
          character, allows you to specify any ASCII control character in
          a variety of formats. C-Kermit 8.0.201 now also lets you
          specify any 8-bit value, 128-255, as the escape character. In
          the SET ESCAPE command, you can type the 8-bit character
          literally or you can enter its numeric code. Here are examples
          that you can enter from a terminal or console that uses the ISO
          Latin-1 character set:

  C-Kermit> set escape 
  C-Kermit> set escape 195
  C-Kermit> show escape
   Escape character: Code 195 (): enabled
  C-Kermit>

          Both of these commands set the escape character value to 195
          (decimal), which happens to be uppercase letter A with Tilde in
          Latin-1. SHOW ESCAPE and SHOW TERMINAL show the value, as does
          the CONNECT message.

   SET TERMINAL AUTODOWNLOAD ERROR { STOP, CONTINUE }
          When Kermit has a terminal connection to another computer, and
          a file transfer is initiated automatically because a Kermit
          packet was received in CONNECT mode (i.e. in the terminal
          screen), this command tells what Kermit should do if the
          transfer fails. The default is to STOP, which leaves Kermit in
          command mode with its file-transfer display showing, so you can
          see that the transfer failed and why. If you SET TERMINAL
          AUTODOWNLOAD ERROR CONTINUE, this causes Kermit to return
          automatically to its terminal screen (i.e. resume its CONNECT
          session) as if the transfer had succeeded; this can be
          desirable if the entire session is under control of a
          host-based script.

   SET TERMINAL BYTESIZE { 7, 8 }
          The byte size to use during CONNECT and INPUT command
          execution, which can be more restrictive than the bytesize
          implied by the current PARITY setting, but not less
          restrictive. In C-Kermit 7.0 and earlier, the terminal bytesize
          was 7 by default to protect against the likelihood that parity
          was in use on the connection without the user's knowledge. When
          the terminal bytesize is 8 (as it is in C-Kermit 8.0 and
          later), the user will see garbage in this (increasingly
          unlikely) situation. Note that 8 data bits are required for
          most character sets other than ASCII: Latin-1, UTF-8, and so
          on.

   A new command has been added to produce timestamped session logs:

   SET TERMINAL SESSION-LOG TIMESTAMPED-TEXT
          Records the terminal session in text mode (like SET TERMINAL
          SESSION-LOG TEXT) but adds a timestamp at the beginning of each
          line. The timestamp format is hh:mm:ss.nnn, and indicates the
          time at which the first character of the line appeared.

   In most UNIX versions (those built with the select()-capable CONNECT
   module -- pretty much all the ones that have or could have TELNET
   included), an idle timeout feature has been added:

   SET TERMINAL IDLE-TIMEOUT number
          If the number is not 0, then Kermit is to take an action when
          the given amount of time passes with no activity during CONNECT
          mode. If the number is positive it is the maximum number of
          idle seconds; if number is negative it represents milliseconds
          (thousandths of seconds). If 0 is given as the number, there
          are no idle timeouts. Synonym: SET TERMINAL IDLE-LIMIT.

   SET TERMINAL IDLE-ACTION { RETURN, HANGUP, EXIT, OUTPUT [ string ] }
          The action to be taken upon an idle timeout in CONNECT mode.
          RETURN to the prompt, HANGUP the connection, EXIT from Kermit,
          or OUTPUT the given string (if no string is given, a NUL (ASCII
          0) character is sent).

   SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT }
          Actions that can be selected on Telnet connections only, that
          might be useful if idle limits are enforced by the Telnet
          server or in the TCP/IP protocol: TELNET-NOP sends a "NO
          Operation" (do-nothing) command, which causes no response from
          the server; TELNET-AYT sends an "Are You There" message to the
          server, which should make the server send back a message.
          Neither of these actions interferes with your remote session.

   SET TERMINAL IDLE-ACTION is useful for connections to hosts or
   services that automatically log you out after a certain amount of idle
   time, e.g.:

  set term idle-timeout 300
  set term idle-action output \32

   sends a space (as if you had pressed the space bar) every 300 seconds
   (five minutes) while there is no activity (32 is the ASCII code for
   space).

   When C-Kermit returns from CONNECT to command mode, the reason for the
   transition is given in a new variable, \v(cx_status):

      0  No CONNECT command given yet.
      1  User escaped back manually.
      2  A trigger string was encountered.
      3  IKSD entered server mode.
      4  Application Program Command received from host.
      5  Idle timeout.
      6  Telnet protocol error.
      7  Keystroke macro.
      8  Time limit exceeded.
    100  Internal error.
    101  Carrier required by not detected.
    102  I/O error on connection.
    103  Disconnected by host.
    104  Disconnected by user.
    105  Session limit exceeded.
    106  Rejected due to Telnet policy.
    107  Received kill signal.

   Values 100 and above indicate there is no connection.

   [ [552]Top ] [ [553]Contents ] [ [554]C-Kermit Home ] [ [555]Kermit
   Home ]
  __________________________________________________________________________

13. CHARACTER SETS

   See the section on [556]file scanning above, and the section on
   character-set conversion in [557]FTP. Also:

     * True support for CP1252 (rather than treating it as Latin-1).
     * Proper handling of C1 values when converting ISO 8-bit text to
       UTF-8.
     * TYPE /CHARACTER-SET: /TRANSLATE-TO: allows specific translations.
     * The TRANSLATE command now works on multiple files.
     * K_CHARSET environment variable to set the file character-set.
     * SET TRANSFER TRANSLATION OFF.
     * FTP client character-set translation ([558]Section 3.7).

   [ [559]Top ] [ [560]Contents ] [ [561]C-Kermit Home ] [ [562]Kermit
   Home ]
  __________________________________________________________________________

14. DIALOUT FROM TELNET TERMINAL SERVERS

   For years, C-Kermit has supported dialing out from Telnet modem
   servers (also called reverse terminal servers or access servers), but
   until now there was no way for Kermit to control the communication
   parameters (speed, parity, etc) on the serial port of the terminal
   server; it had to use whatever was there.

   But now, if you make a connection to a server that supports the Telnet
   Com Port Control Option, [563]RFC 2217, you have the same degree of
   control as you would have over a serial port on the computer where
   Kermit is running: SET SPEED, SET FLOW, SET PARITY, SET STOP-BITS,
   SHOW COMM, WAIT, SET CARRIER-WATCH, the modem-signal variables,
   sending Break, and so on, apply to the connection between the terminal
   server and the modem.

   For example, using a Cisco Access Server 2509, where specifying a TCP
   port in the 6000's selects a serial port that can be used for dialing
   out:

  set host xxx 6001      ; xxx is the IP hostname or address of the server
  (log in if necessary)  ; With a script or by hand
  set modem type usr     ; Tell Kermit what kind of modem it has
  set speed 57600        ; This affects the server's port
  set flow rts/cts       ; Ditto
  dial 7654321

   The modem server might or might not require a login sequence. It might
   also allow for automatic authentication, e.g. via Kerberos tickets.
   NOTE: If the modem server requires a login sequence, then REDIAL might
   not work as expected.

   When you have a Telnet Com Port connection, your SET SPEED and SET
   FLOW options change automatically to reflect the capabilities of the
   server, rather than those of your local computer.

   See the configuration manual for your server for additional
   information. For example, how to set up the server to drop the Telnet
   connection automatically when the telephone call is hung up (e.g.
   "autohangup" on Cisco models).

   For a Linux-based Telnet Com-Port server, click the Srdird link:

   [ [564]Top ] [ [565]Contents ] [ [566]Sredird ] [ [567]C-Kermit Home ]
   [ [568]Kermit Home ]
  __________________________________________________________________________

15. COPING WITH BROKEN KERMIT PARTNERS

   There are lots of faulty Kermit protocol implementations out there,
   found mainly in 3rd-party products ranging from communications
   software packages to file-transfer functions imbedded within devices.
   This topic is covered [569]HERE for C-Kermit 7.0, but C-Kermit 8.0
   adds some additional tricks.

   SET ATTRIBUTE RECORD-FORMAT { ON, OFF }
          Allows control of the Kermit's Record-Format attribute. Set
          this to OFF in case incoming file are refused due to unknown or
          invalid record formats if you want to accept the file anyway.

   SET SEND I-PACKETS { ON, OFF }
          A Kermit server is supposed to accept I-packets; this is how
          the client lets the server know its capabilities and
          preferences before sending a command. Apparently there is at
          least one Kermit server implementation that does not accept
          I-packets, and does not properly respond with an Error packet
          if it gets one. To get around such situations in C-Kermit 8.0,
          you can use SET SEND I-PACKETS OFF to inhibit the sending of I
          packets. In this case, the client must be able to adjust to the
          server's configuration, rather than the other way around as we
          are used to.

   SET PROTOCOL KERMIT {} {} {}
          C-Kermit 6.0 and later automatically send "autoupload" and
          "autodownload" commands when in local mode and you give a file
          transfer command. For example, if you tell kermit to "send
          oofa.txt", Kermit sends "kermit -r" and a carriage return, in
          case you had forgotten to start Kermit on the far end and told
          it to receive a file. If a Kermit program had already been
          started on the far end, it should harmlessly absorb this
          string. However, some Kermit programs violate the Kermit
          protocol definition and treat such strings as Kermit packets
          even though they are not. In such cases, give this command to
          set the Kermit protocol autoupload and download strings to
          nothing, which tells Kermit not to send them. (This is not a
          new feature, but it was not previously included in the "Coping"
          section of the documentation.)

   [ [570]Top ] [ [571]Contents ] [ [572]C-Kermit Home ] [ [573]Kermit
   Home ]
  __________________________________________________________________________

16. NEW COMMAND-LINE OPTIONS

   kermit -h Now prints a complete listing of its command-line options,
   rather than an abbreviated list squeezed into a 24x80 space.

   -dd              Debug, like -d but adds timestamps
   --version  Shows C-Kermit version number.
   --noperms  Equivalent to SET ATTRIBUTE PROTECTION OFF.

   Kermit now accepts a selection of URLs (Universal Resource Locators)
   as its first command-line argument. These are:

   telnet:hostname
          Makes a Telnet connection to the given host (IP hostname or
          address).

   ftp://[user[:password]@]hostname[/path...]
          Makes an FTP connection to the given host (IP hostname or
          address). If a username is given, Kermit tries to log you in;
          if a password is given, it is used; if not, you are prompted
          for one. If no username is given, an anonymous login is
          performed. If a pathname is included, Kermit tries to GET the
          given file. See [574]Section 3.1.3 for details.

   ftps://[user[:password]@]hostname[/path...]
          Makes a secure FTP connection over SSL.

   telnets://[user[:password]@]hostname
          Makes a secure Telnet connection over SSL.

   kermit://[user[:password]@]hostname[/path...]
          Makes a connection to an [575]Internet Kermit Server.

   http://[user[:password]@]hostname[/path...]
          Makes a connection to Web server.

   https://[user[:password]@]hostname[/path...]
          Makes a connection to secure Web server.

   [ [576]Top ] [ [577]Contents ] [ [578]C-Kermit Home ] [ [579]Kermit
   Home ]
  __________________________________________________________________________

17. LOGS

   In C-Kermit 8.0, we make an effort to keep passwords out of the debug
   log. This can never be 100% effective, but it's better than before,
   when there were no precautions at all. Whenever Kermit knows it's
   prompting for, parsing, or transmitting a password, it temporarily
   turns off logging and then turns it back on afterwards. This keeps the
   debug log password-free in most common cases, but there can be no
   guarantees.

   As noted elsewhere, the new "-dd" command-line option selects a
   timestamped debug log (equivalent to "set debug timestamps on", "log
   debug debug.log").

   C-Kermit 8.0 also supports a new timestamped session log via "set
   session-log timestamped-text", "log session".

   There have been requests for other kinds of logs, for example a
   command log. These might be added at some point. One person wanted to
   be able to log commands with timestamps, but only commands issued at
   the prompt, not commands from files or macros, and also wanted a
   header line at the beginning showing the date, user, and host. This
   can be done as follows:

  .filename := \v(home)commands.log  ; (for example)
  fopen /write \%c \m(filename)
  if success {
      fwrite /line \%c \v(date): User=\v(user) Host=\v(host)
      fclose \%c
      set debug timestamps on
      log debug {| grep "CMD(P)" >> \m(filename)} append
  }

   [ [580]Top ] [ [581]Contents ] [ [582]C-Kermit Home ] [ [583]Kermit
   Home ]
     _________________________________________________________________

   C-Kermit 8.0 Update Notes / [584]The Kermit Project / Columbia
   University / 15 Dec 2003

References

   1. http://www.columbia.edu/kermit/ckermit80.html#contents
   2. http://www.columbia.edu/kermit/ckermit.html
   3. http://www.columbia.edu/kermit/index.html
   4. http://www.columbia.edu/kermit/ckermit80.html
   5. mailto:kermit-support@columbia.edu
   6. http://www.columbia.edu/kermit/
   7. http://www.kermit-project.org/
   8. http://www.columbia.nyc.ny.us/kermit/
   9. ftp://kermit.columbia.edu/kermit/f/COPYING.TXT
  10. ftp://kermit.columbia.edu/kermit/f/ckcmai.c
  11. http://www.columbia.edu/kermit/ckermit80.html#xv
  12. http://www.columbia.edu/kermit/ck60manual.html
  13. http://www.columbia.edu/kermit/ckermi70.html
  14. ftp://kermit.columbia.edu/kermit/f/ckermit70.txt
  15. http://www.columbia.edu/kermit/ckututor.html
  16. ftp://kermit.columbia.edu/kermit/f/ckuker.nr
  17. http://www.columbia.edu/kermit/security.htm
  18. http://www.columbia.edu/kermit/telnet.htm
  19. http://www.columbia.edu/kermit/ftpscripts.html
  20. http://www.columbia.edu/kermit/ckcbwr.html
  21. ftp://kermit.columbia.edu/kermit/f/ckcbwr.txt
  22. http://www.columbia.edu/kermit/ckubwr.html
  23. ftp://kermit.columbia.edu/kermit/f/ckubwr.txt
  24. http://www.columbia.edu/kermit/ckvbwr.html
  25. ftp://kermit.columbia.edu/kermit/f/ckvbwr.txt
  26. http://www.columbia.edu/kermit/ckuins.html
  27. ftp://kermit.columbia.edu/kermit/f/ckuins.txt
  28. http://www.columbia.edu/kermit/ckvins.html
  29. ftp://kermit.columbia.edu/kermit/f/ckvins.txt
  30. http://www.columbia.edu/kermit/ckccfg.html
  31. ftp://kermit.columbia.edu/kermit/f/ckccfg.txt
  32. http://www.columbia.edu/kermit/ckcplm.html
  33. ftp://kermit.columbia.edu/kermit/f/ckcplm.txt
  34. http://www.columbia.edu/kermit/iksd.html
  35. http://www.columbia.edu/kermit/skermit.html
  36. http://www.columbia.edu/kermit/ckermit80.html#top
  37. http://www.columbia.edu/kermit/ckermit.html
  38. http://www.columbia.edu/kermit/index.html
  39. http://www.columbia.edu/kermit/ckermit80.html#x0
  40. http://www.columbia.edu/kermit/ckermit80.html#x1
  41. http://www.columbia.edu/kermit/ckermit80.html#x2
  42. http://www.columbia.edu/kermit/ckermit80.html#x2.1
  43. http://www.columbia.edu/kermit/ckermit80.html#x2.2
  44. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1
  45. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2
  46. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3
  47. http://www.columbia.edu/kermit/ckermit80.html#x2.2.4
  48. http://www.columbia.edu/kermit/ckermit80.html#x2.2.5
  49. http://www.columbia.edu/kermit/ckermit80.html#x2.2.6
  50. http://www.columbia.edu/kermit/ckermit80.html#x3
  51. http://www.columbia.edu/kermit/ckermit80.html#x3.1
  52. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1
  53. http://www.columbia.edu/kermit/ckermit80.html#x3.1.2
  54. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  55. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
  56. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  57. http://www.columbia.edu/kermit/ckermit80.html#x3.3
  58. http://www.columbia.edu/kermit/ckermit80.html#x3.4
  59. http://www.columbia.edu/kermit/ckermit80.html#x3.5
  60. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1
  61. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
  62. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3
  63. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  64. http://www.columbia.edu/kermit/ckermit80.html#x3.6.1
  65. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
  66. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3
  67. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  68. http://www.columbia.edu/kermit/ckermit80.html#x3.7.1
  69. http://www.columbia.edu/kermit/ckermit80.html#x3.7.2
  70. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  71. http://www.columbia.edu/kermit/ckermit80.html#x3.9
  72. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  73. http://www.columbia.edu/kermit/ckermit80.html#x3.10.1
  74. http://www.columbia.edu/kermit/ckermit80.html#x3.10.2
  75. http://www.columbia.edu/kermit/ckermit80.html#x3.10.3
  76. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  77. http://www.columbia.edu/kermit/ckermit80.html#x4
  78. http://www.columbia.edu/kermit/ckermit80.html#x5
  79. http://www.columbia.edu/kermit/ckermit80.html#x6
  80. http://www.columbia.edu/kermit/ckermit80.html#x6.1
  81. http://www.columbia.edu/kermit/ckermit80.html#x6.2
  82. http://www.columbia.edu/kermit/ckermit80.html#x6.3
  83. http://www.columbia.edu/kermit/ckermit80.html#x6.4
  84. http://www.columbia.edu/kermit/ckermit80.html#x6.5
  85. http://www.columbia.edu/kermit/ckermit80.html#x6.6
  86. http://www.columbia.edu/kermit/ckermit80.html#x7
  87. http://www.columbia.edu/kermit/ckermit80.html#x8
  88. http://www.columbia.edu/kermit/ckermit80.html#x8.1
  89. http://www.columbia.edu/kermit/ckermit80.html#x8.2
  90. http://www.columbia.edu/kermit/ckermit80.html#x8.3
  91. http://www.columbia.edu/kermit/ckermit80.html#x8.4
  92. http://www.columbia.edu/kermit/ckermit80.html#x8.5
  93. http://www.columbia.edu/kermit/ckermit80.html#x8.6
  94. http://www.columbia.edu/kermit/ckermit80.html#x8.7
  95. http://www.columbia.edu/kermit/ckermit80.html#x8.8
  96. http://www.columbia.edu/kermit/ckermit80.html#x8.9
  97. http://www.columbia.edu/kermit/ckermit80.html#x8.10
  98. http://www.columbia.edu/kermit/ckermit80.html#x8.11
  99. http://www.columbia.edu/kermit/ckermit80.html#x8.12
 100. http://www.columbia.edu/kermit/ckermit80.html#x8.13
 101. http://www.columbia.edu/kermit/ckermit80.html#x8.14
 102. http://www.columbia.edu/kermit/ckermit80.html#x9
 103. http://www.columbia.edu/kermit/ckermit80.html#x9.1
 104. http://www.columbia.edu/kermit/ckermit80.html#x9.2
 105. http://www.columbia.edu/kermit/ckermit80.html#x9.3
 106. http://www.columbia.edu/kermit/ckermit80.html#x9.4
 107. http://www.columbia.edu/kermit/ckermit80.html#x9.5
 108. http://www.columbia.edu/kermit/ckermit80.html#x9.6
 109. http://www.columbia.edu/kermit/ckermit80.html#x9.7
 110. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 111. http://www.columbia.edu/kermit/ckermit80.html#x9.9
 112. http://www.columbia.edu/kermit/ckermit80.html#x9.10
 113. http://www.columbia.edu/kermit/ckermit80.html#x9.11
 114. http://www.columbia.edu/kermit/ckermit80.html#x10
 115. http://www.columbia.edu/kermit/ckermit80.html#x11
 116. http://www.columbia.edu/kermit/ckermit80.html#x12
 117. http://www.columbia.edu/kermit/ckermit80.html#x13
 118. http://www.columbia.edu/kermit/ckermit80.html#x14
 119. http://www.columbia.edu/kermit/ckermit80.html#x15
 120. http://www.columbia.edu/kermit/ckermit80.html#x16
 121. http://www.columbia.edu/kermit/ckermit80.html#x17
 122. http://www.columbia.edu/kermit/ckermit80.html#top
 123. http://www.columbia.edu/kermit/ckermit.html
 124. http://www.columbia.edu/kermit/index.html
 125. http://www.columbia.edu/kermit/ckuins.html#x5
 126. http://www.columbia.edu/kermit/ckuins.html
 127. http://www.columbia.edu/kermit/ckermit80.html#x5
 128. http://www.columbia.edu/kermit/ckermit80.html#x2.2
 129. http://www.columbia.edu/kermit/ckermit80.html#contents
 130. http://www.columbia.edu/kermit/ckermit80.html#x15
 131. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 132. http://www.columbia.edu/kermit/ckermit80.html#ftpdates
 133. http://www.columbia.edu/kermit/ckermit80.html#ftpcheck
 134. http://www.columbia.edu/kermit/ckermit80.html#ftpnamelist
 135. http://www.columbia.edu/kermit/ckermit80.html#srvrename
 136. http://www.columbia.edu/kermit/ckermit80.html#ftpvdir
 137. http://www.columbia.edu/kermit/ckermit80.html#setftptype
 138. http://www.columbia.edu/kermit/ckermit80.html#x3.6
 139. http://www.columbia.edu/kermit/ckermit80.html#x15
 140. http://www.columbia.edu/kermit/ckermit80.html#x8.7
 141. http://www.columbia.edu/kermit/ckermit80.html#x2.1
 142. http://www.columbia.edu/kermit/ckermit80.html#x2.2
 143. http://www.columbia.edu/kermit/ckermit80.html#x8.14
 144. http://www.columbia.edu/kermit/ckermit80.html#x8.13
 145. http://www.columbia.edu/kermit/ckermit80.html#x8.13
 146. http://www.columbia.edu/kermit/ckututor.html
 147. http://www.columbia.edu/kermit/ckuins.html
 148. http://www.columbia.edu/kermit/skermit.html
 149. http://www.columbia.edu/kermit/ckermit80.html#setlocus
 150. http://www.columbia.edu/kermit/ckermit80.html#lcommands
 151. http://www.columbia.edu/kermit/ckermit80.html#ftpuser
 152. http://www.columbia.edu/kermit/ckermit80.html#showvar
 153. http://www.columbia.edu/kermit/ckermit80.html#callerid
 154. http://www.columbia.edu/kermit/ckermit80.html#x6.6
 155. http://www.columbia.edu/kermit/ckermit80.html#x0
 156. http://www.columbia.edu/kermit/ckermit80.html#x3.11
 157. http://www.columbia.edu/kermit/ckermit80.html#top
 158. http://www.columbia.edu/kermit/ckermit80.html#contents
 159. http://www.columbia.edu/kermit/ckermit.html
 160. http://www.columbia.edu/kermit/index.html
 161. http://www.columbia.edu/kermit/ckermit80.html#x0
 162. http://www.columbia.edu/kermit/ckermit80.html#top
 163. http://www.columbia.edu/kermit/ckermit80.html#contents
 164. http://www.columbia.edu/kermit/ckermit.html
 165. http://www.columbia.edu/kermit/index.html
 166. http://www.columbia.edu/kermit/k95.html
 167. http://www.columbia.edu/kermit/sshclient.html
 168. http://www.columbia.edu/kermit/skermit.html
 169. http://www.columbia.edu/kermit/skermit.html
 170. http://www.columbia.edu/kermit/sshclien.htm
 171. http://www.columbia.edu/kermit/ckermit80.html#x3
 172. ftp://ftp.isi.edu/in-notes/rfc1738.txt
 173. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2
 174. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1
 175. ftp://ftp.isi.edu/in-notes/rfc2396.txt
 176. ftp://ftp.isi.edu/in-notes/rfc2616.txt
 177. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3
 178. ftp://ftp.isi.edu/in-notes/rfc2616.txt
 179. http://www.columbia.edu/kermit/ckermit80.html#x8.13.7
 180. http://www.columbia.edu/kermit/security.htm#x5.4
 181. http://www.columbia.edu/kermit/security.htm#x15
 182. http://www.columbia.edu/kermit/security.htm#x6.2
 183. http://www.columbia.edu/kermit/security.html
 184. http://www.columbia.edu/kermit/ckermit80.html#x16
 185. http://www.columbia.edu/kermit/ckermit80.html#top
 186. http://www.columbia.edu/kermit/ckermit80.html#contents
 187. http://www.columbia.edu/kermit/ckermit.html
 188. http://www.columbia.edu/kermit/index.html
 189. http://www.columbia.edu/kermit/ckermit80.html#x3.1
 190. http://www.columbia.edu/kermit/ckermit80.html#x3.2
 191. http://www.columbia.edu/kermit/ckermit80.html#x3.3
 192. http://www.columbia.edu/kermit/ckermit80.html#x3.4
 193. http://www.columbia.edu/kermit/ckermit80.html#x3.5
 194. http://www.columbia.edu/kermit/ckermit80.html#x3.6
 195. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 196. http://www.columbia.edu/kermit/ckermit80.html#x3.8
 197. http://www.columbia.edu/kermit/ckermit80.html#x3.9
 198. http://www.columbia.edu/kermit/ckermit80.html#x3.10
 199. http://www.columbia.edu/kermit/ckermit80.html#x3.11
 200. http://www.columbia.edu/kermit/security.htm
 201. http://www.columbia.edu/kermit/security.htm#servers
 202. http://www.columbia.edu/kermit/ckcsets.html
 203. http://www.columbia.edu/kermit/unicode.html
 204. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4
 205. http://www.columbia.edu/kermit/case10.html
 206. http://www.columbia.edu/kermit/ckermit80.html#x4
 207. http://www.columbia.edu/kermit/ckermit80.html#x3.11
 208. http://www.columbia.edu/kermit/ftpscripts.html
 209. http://www.columbia.edu/kermit/ckermit80.html#top
 210. http://www.columbia.edu/kermit/ckermit80.html#ftp
 211. http://www.columbia.edu/kermit/ftpclient.html
 212. http://www.columbia.edu/kermit/ftpscripts.html
 213. http://www.columbia.edu/kermit/ckermit.html
 214. http://www.columbia.edu/kermit/index.html
 215. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1
 216. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
 217. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
 218. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
 219. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
 220. http://www.columbia.edu/kermit/ckermit80.html#x3.2
 221. http://www.columbia.edu/kermit/ckermit80.html#x3.5
 222. http://www.columbia.edu/kermit/ckermit80.html#x3.6
 223. http://www.columbia.edu/kermit/ftpscripts.html
 224. http://www.columbia.edu/kermit/ckb2.htm
 225. http://www.columbia.edu/kermit/ckermit80.html#ftpautolog
 226. http://www.columbia.edu/kermit/ckermit80.html#ftpuser
 227. http://www.columbia.edu/kermit/ckermit80.html#x3.8
 228. http://www.columbia.edu/kermit/ckermit80.html#x3.8
 229. http://www.columbia.edu/kermit/ckermit80.html#top
 230. http://www.columbia.edu/kermit/ckermit80.html#ftp
 231. http://www.columbia.edu/kermit/ckermit.html
 232. http://www.columbia.edu/kermit/index.html
 233. http://www.columbia.edu/kermit/ibm_ie.html
 234. http://www.columbia.edu/kermit/ckermit80.html#x3.10
 235. http://www.columbia.edu/kermit/ckermit80.html#top
 236. http://www.columbia.edu/kermit/ckermit80.html#ftp
 237. http://www.columbia.edu/kermit/ckermit.html
 238. http://www.columbia.edu/kermit/index.html
 239. http://www.columbia.edu/kermit/ck60manual.html
 240. http://www.columbia.edu/kermit/ckermit70.html#x4.17
 241. http://www.columbia.edu/kermit/ckermit70.html
 242. http://www.columbia.edu/kermit/ckermit80.html#x3.6
 243. http://www.columbia.edu/kermit/ckermit80.html#x3.11
 244. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
 245. http://www.columbia.edu/kermit/security.html
 246. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 247. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 248. http://www.columbia.edu/kermit/ckermit80.html#x8.13.4
 249. http://www.columbia.edu/kermit/ckermit80.html#permswitch
 250. http://www.columbia.edu/kermit/ckermit80.html#ftpchmod
 251. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
 252. http://www.columbia.edu/kermit/ckermit80.html#x4
 253. http://www.columbia.edu/kermit/ckermit80.html#top
 254. http://www.columbia.edu/kermit/ckermit80.html#ftp
 255. http://www.columbia.edu/kermit/ckermit.html
 256. http://www.columbia.edu/kermit/index.html
 257. http://www.columbia.edu/kermit/ckermit80.html#x7
 258. http://www.columbia.edu/kermit/ckermit80.html#x3.8
 259. http://www.columbia.edu/kermit/ckermit80.html#x3.8
 260. http://www.columbia.edu/kermit/ckb2.htm
 261. http://www.columbia.edu/kermit/ckermit80.html#x3.10
 262. http://www.columbia.edu/kermit/ckermit80.html#x3.10
 263. http://www.columbia.edu/kermit/ckermit80.html#x3.6
 264. http://www.columbia.edu/kermit/ckermit80.html#setftptype
 265. http://www.columbia.edu/kermit/ckermit80.html#top
 266. http://www.columbia.edu/kermit/ckermit80.html#ftp
 267. http://www.columbia.edu/kermit/ckermit.html
 268. http://www.columbia.edu/kermit/index.html
 269. http://www.columbia.edu/kermit/ckermit70.html#x4.9
 270. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1
 271. http://www.columbia.edu/kermit/ckermit80.html#erroraction
 272. http://www.columbia.edu/kermit/ckermit70.html#x1.5
 273. http://www.columbia.edu/kermit/ckermit70.html#x4.7
 274. http://www.columbia.edu/kermit/ckermit70.html#x1.6
 275. http://www.columbia.edu/kermit/ckermit80.html#x8.13
 276. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4
 277. http://www.columbia.edu/kermit/ckermi70.htm
 278. http://www.columbia.edu/kermit/ckermit80.html#x4
 279. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 280. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
 281. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 282. http://www.columbia.edu/kermit/ckermit80.html#erroraction
 283. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
 284. http://www.columbia.edu/kermit/ckermit80.html#erroraction
 285. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
 286. http://www.columbia.edu/kermit/ckermit80.html#ftpperms
 287. http://www.columbia.edu/kermit/ckermit80.html#ftpunique
 288. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
 289. http://www.columbia.edu/kermit/ckermit80.html#note_utc
 290. http://www.columbia.edu/kermit/ckermit80.html#note_date
 291. http://www.columbia.edu/kermit/ckermit80.html#x3.6
 292. http://www.boulder.nist.gov/timefreq/faq/faq.htm#10:
 293. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 294. http://www.columbia.edu/kermit/ckermit80.html#top
 295. http://www.columbia.edu/kermit/ckermit80.html#ftp
 296. http://www.columbia.edu/kermit/ckermit.html
 297. http://www.columbia.edu/kermit/index.html
 298. http://www.columbia.edu/kermit/ckermit80.html#x3.11
 299. http://www.columbia.edu/kermit/ckermi70.htm#x4.3
 300. http://www.columbia.edu/kermit/ckermit70.html
 301. http://www.columbia.edu/kermit/ckermit80.html#x5
 302. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3
 303. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
 304. http://www.columbia.edu/kermit/ckermi70.htm#x4.1
 305. http://www.columbia.edu/kermit/ckermi70.htm#x4.2.2
 306. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4
 307. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
 308. http://www.columbia.edu/kermit/ckermit80.html#x3.11
 309. http://www.columbia.edu/kermit/ckermit80.html#x3.11
 310. http://www.columbia.edu/kermit/ckermit80.html#srvrename
 311. http://www.columbia.edu/kermit/ckermi70.htm#x4.1
 312. http://www.columbia.edu/kermit/ckermi70.htm
 313. http://www.columbia.edu/kermit/ckb2.htm
 314. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
 315. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3
 316. http://www.proftpd.net/
 317. http://www.columbia.edu/kermit/ckermit80.html#top
 318. http://www.columbia.edu/kermit/ckermit80.html#ftp
 319. http://www.columbia.edu/kermit/ckermit.html
 320. http://www.columbia.edu/kermit/index.html
 321. http://www.columbia.edu/kermit/ckb2.htm
 322. http://www.columbia.edu/kermit/ckcsets.html
 323. http://www.columbia.edu/kermit/unicode.html
 324. http://www.columbia.edu/kermit/ckcsets.html
 325. http://www.columbia.edu/kermit/ckcsets.html
 326. http://www.columbia.edu/kermit/ckermit80.html#x4
 327. http://www.columbia.edu/kermit/utf8.html
 328. http://www.columbia.edu/kermit/ckcsets.html
 329. http://www.columbia.edu/kermit/ckermit80.html#x4
 330. ftp://ftp.isi.edu/in-notes/rfc2640.txt
 331. http://www.columbia.edu/kermit/ckermit80.html#top
 332. http://www.columbia.edu/kermit/ckermit80.html#ftp
 333. http://www.columbia.edu/kermit/ckermit.html
 334. http://www.columbia.edu/kermit/index.html
 335. http://www.columbia.edu/kermit/ckermit80.html#top
 336. http://www.columbia.edu/kermit/ckermit80.html#ftp
 337. http://www.columbia.edu/kermit/ckermit.html
 338. http://www.columbia.edu/kermit/index.html
 339. http://www.columbia.edu/kermit/ckermit80.html#top
 340. http://www.columbia.edu/kermit/ckermit80.html#ftp
 341. http://www.columbia.edu/kermit/ckermit.html
 342. http://www.columbia.edu/kermit/index.html
 343. http://www.columbia.edu/kermit/ftpscripts.html
 344. http://www.columbia.edu/kermit/ckermit80.html#x3.2
 345. http://www.columbia.edu/kermit/ckermit80.html#x3.2
 346. ftp://ftp.isi.edu/in-notes/rfc959.txt
 347. http://www.columbia.edu/kermit/ckscripts.html
 348. http://www.columbia.edu/kermit/ckermit80.html#top
 349. http://www.columbia.edu/kermit/ckermit80.html#ftp
 350. http://www.columbia.edu/kermit/ftpscript.html
 351. http://www.columbia.edu/kermit/ckermit.html
 352. http://www.columbia.edu/kermit/index.html
 353. http://www.columbia.edu/kermit/ckermit80.html#x3.11.1
 354. http://www.columbia.edu/kermit/ckermit80.html#x3.11.2
 355. http://www.columbia.edu/kermit/ckermit80.html#x3.11.3
 356. http://www.columbia.edu/kermit/ckermit80.html#x3.11.4
 357. http://www.columbia.edu/kermit/ckermit80.html#x3.11.5
 358. http://www.columbia.edu/kermit/ckermit.html
 359. http://www.columbia.edu/kermit/k95.html
 360. http://www.columbia.edu/kermit/ckermit80.html#x3.11.5
 361. ftp://ftp.isi.edu/in-notes/rfc959.txt
 362. ftp://ftp.isi.edu/in-notes/rfc2389.txt
 363. http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-16.txt
 364. http://www.columbia.edu/kermit/ftpclient.html
 365. http://www.columbia.edu/kermit/ckermit80.html#top
 366. http://www.columbia.edu/kermit/ckermit80.html#ftp
 367. http://www.columbia.edu/kermit/ckermit.html
 368. http://www.columbia.edu/kermit/index.html
 369. http://www.columbia.edu/kermit/ckermit80.html#x3
 370. http://www.columbia.edu/kermit/ckermit80.html#ucs2
 371. http://www.columbia.edu/kermit/ckermit80.html#top
 372. http://www.columbia.edu/kermit/ckermit80.html#contents
 373. http://www.columbia.edu/kermit/ckermit.html
 374. http://www.columbia.edu/kermit/index.html
 375. http://www.columbia.edu/kermit/ckermit80.html#top
 376. http://www.columbia.edu/kermit/ckermit80.html#contents
 377. http://www.columbia.edu/kermit/ckermit.html
 378. http://www.columbia.edu/kermit/index.html
 379. http://www.columbia.edu/kermit/ckb2.htm
 380. http://www.columbia.edu/kermit/ckermit80.html#top
 381. http://www.columbia.edu/kermit/ckermit80.html#contents
 382. http://www.columbia.edu/kermit/ckermit.html
 383. http://www.columbia.edu/kermit/index.html
 384. http://www.columbia.edu/kermit/ckermit80.html#x4
 385. http://www.columbia.edu/kermit/ckermit80.html#x4
 386. http://www.columbia.edu/kermit/ckermit80.html#x8.12
 387. http://www.columbia.edu/kermit/ckermit80.html#x8.1
 388. http://www.columbia.edu/kermit/ckermit80.html#x12
 389. http://www.columbia.edu/kermit/ckermit80.html#x8.12
 390. http://www.columbia.edu/kermit/ckermit80.html#top
 391. http://www.columbia.edu/kermit/ckermit80.html#contents
 392. http://www.columbia.edu/kermit/ckermit.html
 393. http://www.columbia.edu/kermit/index.html
 394. http://www.columbia.edu/kermit/ckermit80.html#x8.14
 395. http://www.columbia.edu/kermit/ckermit80.html#top
 396. http://www.columbia.edu/kermit/ckermit80.html#contents
 397. http://www.columbia.edu/kermit/ckermit.html
 398. http://www.columbia.edu/kermit/index.html
 399. http://www.columbia.edu/kermit/ckermit80.html#x9
 400. http://www.columbia.edu/kermit/ckermit80.html#top
 401. http://www.columbia.edu/kermit/ckermit80.html#contents
 402. http://www.columbia.edu/kermit/ckermit.html
 403. http://www.columbia.edu/kermit/index.html
 404. http://www.columbia.edu/kermit/ckermit80.html#x8.6
 405. http://www.columbia.edu/kermit/ckermit80.html#top
 406. http://www.columbia.edu/kermit/ckermit80.html#contents
 407. http://www.columbia.edu/kermit/ckermit.html
 408. http://www.columbia.edu/kermit/index.html
 409. http://www.columbia.edu/kermit/ckermit80.html#top
 410. http://www.columbia.edu/kermit/ckermit80.html#contents
 411. http://www.columbia.edu/kermit/ckermit.html
 412. http://www.columbia.edu/kermit/index.html
 413. http://www.columbia.edu/kermit/ckermit80.html#top
 414. http://www.columbia.edu/kermit/ckermit80.html#contents
 415. http://www.columbia.edu/kermit/ckermit.html
 416. http://www.columbia.edu/kermit/index.html
 417. http://www.columbia.edu/kermit/ckermit80.html#fjoin
 418. http://www.columbia.edu/kermit/ckermit80.html#fsplit
 419. http://www.columbia.edu/kermit/ckermit80.html#x8.10
 420. http://www.columbia.edu/kermit/ckermit80.html#top
 421. http://www.columbia.edu/kermit/ckermit80.html#contents
 422. http://www.columbia.edu/kermit/ckermit.html
 423. http://www.columbia.edu/kermit/index.html
 424. http://www.columbia.edu/kermit/ckermit80.html#x9
 425. http://www.columbia.edu/kermit/ckermit80.html#x9
 426. http://www.columbia.edu/kermit/ckermit80.html#x9
 427. http://www.columbia.edu/kermit/ckermit80.html#x3
 428. http://www.columbia.edu/kermit/ckermit80.html#x3
 429. http://www.columbia.edu/kermit/ckermit80.html#x3.2
 430. http://www.columbia.edu/kermit/ckermit80.html#x3.2
 431. http://www.columbia.edu/kermit/ckermit80.html#x3.8
 432. http://www.columbia.edu/kermit/ckermit80.html#x3
 433. http://www.columbia.edu/kermit/ckermit80.html#x3
 434. http://www.columbia.edu/kermit/ckermit80.html#x3
 435. http://www.columbia.edu/kermit/ckermit80.html#x3.2
 436. http://www.columbia.edu/kermit/ckermit80.html#x3
 437. http://www.columbia.edu/kermit/ckermit80.html#x8.13
 438. http://www.columbia.edu/kermit/ckermit80.html#x8.13
 439. http://www.columbia.edu/kermit/ckermit80.html#x9
 440. http://www.columbia.edu/kermit/ckermit80.html#x8.10
 441. http://www.columbia.edu/kermit/ckermit80.html#x8.7.4
 442. http://www.columbia.edu/kermit/ckermit80.html#top
 443. http://www.columbia.edu/kermit/ckermit80.html#contents
 444. http://www.columbia.edu/kermit/ckermit.html
 445. http://www.columbia.edu/kermit/index.html
 446. http://www.columbia.edu/kermit/ckermit80.html#top
 447. http://www.columbia.edu/kermit/ckermit80.html#contents
 448. http://www.columbia.edu/kermit/ckermit.html
 449. http://www.columbia.edu/kermit/index.html
 450. http://www.columbia.edu/kermit/ckermit80.html#top
 451. http://www.columbia.edu/kermit/ckermit80.html#contents
 452. http://www.columbia.edu/kermit/ckermit.html
 453. http://www.columbia.edu/kermit/index.html
 454. http://www.columbia.edu/kermit/ckermit80.html#x8.7
 455. http://www.columbia.edu/kermit/ckermit80.html#top
 456. http://www.columbia.edu/kermit/ckermit80.html#contents
 457. http://www.columbia.edu/kermit/ckermit.html
 458. http://www.columbia.edu/kermit/index.html
 459. http://www.columbia.edu/kermit/ckermit80.html#scriptedit
 460. http://www.columbia.edu/kermit/ckermit80.html#top
 461. http://www.columbia.edu/kermit/ckermit80.html#contents
 462. http://www.columbia.edu/kermit/ckermit.html
 463. http://www.columbia.edu/kermit/index.html
 464. http://www.columbia.edu/kermit/ckermit80.html#top
 465. http://www.columbia.edu/kermit/ckermit80.html#contents
 466. http://www.columbia.edu/kermit/ckermit.html
 467. http://www.columbia.edu/kermit/index.html
 468. ftp://ftp.isi.edu/in-notes/rfc2822.txt
 469. ftp://ftp.isi.edu/in-notes/rfc2822.txt
 470. ftp://ftp.isi.edu/in-notes/rfc2822.txt
 471. ftp://ftp.isi.edu/in-notes/rfc2822.txt
 472. http://www.columbia.edu/kermit/ckermit80.html#top
 473. http://www.columbia.edu/kermit/ckermit80.html#contents
 474. http://www.columbia.edu/kermit/ckermit.html
 475. http://www.columbia.edu/kermit/index.html
 476. http://www.columbia.edu/kermit/ckermit80.html#x8.1
 477. http://www.columbia.edu/kermit/ckermit80.html#top
 478. http://www.columbia.edu/kermit/ckermit80.html#contents
 479. http://www.columbia.edu/kermit/ckermit.html
 480. http://www.columbia.edu/kermit/index.html
 481. http://www.columbia.edu/kermit/ckermit80.html#x8.2
 482. http://www.columbia.edu/kermit/ckermit80.html#top
 483. http://www.columbia.edu/kermit/ckermit80.html#contents
 484. http://www.columbia.edu/kermit/ckermit.html
 485. http://www.columbia.edu/kermit/index.html
 486. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 487. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 488. http://www.columbia.edu/kermit/ckermit80.html#x8.2
 489. http://www.columbia.edu/kermit/ckermit80.html#top
 490. http://www.columbia.edu/kermit/ckermit80.html#contents
 491. http://www.columbia.edu/kermit/ckermit.html
 492. http://www.columbia.edu/kermit/index.html
 493. http://www.columbia.edu/kermit/ckermit80.html#top
 494. http://www.columbia.edu/kermit/ckermit80.html#contents
 495. http://www.columbia.edu/kermit/ckermit.html
 496. http://www.columbia.edu/kermit/index.html
 497. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 498. http://www.columbia.edu/kermit/ckermit80.html#top
 499. http://www.columbia.edu/kermit/ckermit80.html#contents
 500. http://www.columbia.edu/kermit/ckermit.html
 501. http://www.columbia.edu/kermit/index.html
 502. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 503. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 504. http://www.columbia.edu/kermit/ckermit80.html#x9.6
 505. http://www.columbia.edu/kermit/ckermit80.html#top
 506. http://www.columbia.edu/kermit/ckermit80.html#contents
 507. http://www.columbia.edu/kermit/ckermit.html
 508. http://www.columbia.edu/kermit/index.html
 509. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 510. http://www.columbia.edu/kermit/ckermit80.html#x9.8
 511. http://www.columbia.edu/kermit/ckermit80.html#top
 512. http://www.columbia.edu/kermit/ckermit80.html#contents
 513. http://www.columbia.edu/kermit/ckermit.html
 514. http://www.columbia.edu/kermit/index.html
 515. http://www.columbia.edu/kermit/ckermit80.html#top
 516. http://www.columbia.edu/kermit/ckermit80.html#contents
 517. http://www.columbia.edu/kermit/ckermit.html
 518. http://www.columbia.edu/kermit/index.html
 519. http://www.columbia.edu/kermit/ckermit80.html#top
 520. http://www.columbia.edu/kermit/ckermit80.html#contents
 521. http://www.columbia.edu/kermit/ckermit.html
 522. http://www.columbia.edu/kermit/index.html
 523. mailto:thucdat@hotmail.com
 524. http://www.columbia.edu/kermit/ckermit80.html#x9.9.2
 525. http://www.columbia.edu/kermit/ckermit80.html#top
 526. http://www.columbia.edu/kermit/ckermit80.html#contents
 527. http://www.columbia.edu/kermit/ckermit.html
 528. http://www.columbia.edu/kermit/index.html
 529. http://www.columbia.edu/kermit/ckermit80.html#top
 530. http://www.columbia.edu/kermit/ckermit80.html#contents
 531. http://www.columbia.edu/kermit/ckermit.html
 532. http://www.columbia.edu/kermit/index.html
 533. http://www.columbia.edu/kermit/ckermit80.html#top
 534. http://www.columbia.edu/kermit/ckermit80.html#contents
 535. http://www.columbia.edu/kermit/ckermit.html
 536. http://www.columbia.edu/kermit/index.html
 537. http://www.columbia.edu/kermit/ckermit80.html#x9.2
 538. http://www.columbia.edu/kermit/ckermit80.html#top
 539. http://www.columbia.edu/kermit/ckermit80.html#contents
 540. http://www.columbia.edu/kermit/ckermit.html
 541. http://www.columbia.edu/kermit/index.html
 542. http://www.columbia.edu/kermit/ckermit80.html#x4
 543. http://www.columbia.edu/kermit/ckermit80.html#x4
 544. http://www.columbia.edu/kermit/ckermit80.html#top
 545. http://www.columbia.edu/kermit/ckermit80.html#contents
 546. http://www.columbia.edu/kermit/ckermit.html
 547. http://www.columbia.edu/kermit/index.html
 548. http://www.columbia.edu/kermit/ckermit80.html#top
 549. http://www.columbia.edu/kermit/ckermit80.html#contents
 550. http://www.columbia.edu/kermit/ckermit.html
 551. http://www.columbia.edu/kermit/index.html
 552. http://www.columbia.edu/kermit/ckermit80.html#top
 553. http://www.columbia.edu/kermit/ckermit80.html#contents
 554. http://www.columbia.edu/kermit/ckermit.html
 555. http://www.columbia.edu/kermit/index.html
 556. http://www.columbia.edu/kermit/ckermit80.html#x4
 557. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 558. http://www.columbia.edu/kermit/ckermit80.html#x3.7
 559. http://www.columbia.edu/kermit/ckermit80.html#top
 560. http://www.columbia.edu/kermit/ckermit80.html#contents
 561. http://www.columbia.edu/kermit/ckermit.html
 562. http://www.columbia.edu/kermit/index.html
 563. ftp://ftp.isi.edu/in-notes/rfc2217.txt
 564. http://www.columbia.edu/kermit/ckermit80.html#top
 565. http://www.columbia.edu/kermit/ckermit80.html#contents
 566. ftp://kermit.columbia.edu/kermit/sredird/
 567. http://www.columbia.edu/kermit/ckermit.html
 568. http://www.columbia.edu/kermit/index.html
 569. http://www.columbia.edu/kermit/ckermi70.htm#x4.22
 570. http://www.columbia.edu/kermit/ckermit80.html#top
 571. http://www.columbia.edu/kermit/ckermit80.html#contents
 572. http://www.columbia.edu/kermit/ckermit.html
 573. http://www.columbia.edu/kermit/index.html
 574. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
 575. http://www.columbia.edu/kermit/cuiksd.html
 576. http://www.columbia.edu/kermit/ckermit80.html#top
 577. http://www.columbia.edu/kermit/ckermit80.html#contents
 578. http://www.columbia.edu/kermit/ckermit.html
 579. http://www.columbia.edu/kermit/index.html
 580. http://www.columbia.edu/kermit/ckermit80.html#top
 581. http://www.columbia.edu/kermit/ckermit80.html#contents
 582. http://www.columbia.edu/kermit/ckermit.html
 583. http://www.columbia.edu/kermit/index.html
 584. http://www.columbia.edu/kermit/index.html