File: ckermit2.upd

package info (click to toggle)
ckermit 193-3
links: PTS
area: non-free
in suites: slink
size: 6,180 kB
ctags: 8,803
sloc: ansic: 118,504; makefile: 2,474; sh: 52
file content (7040 lines) | stat: -rw-r--r-- 295,520 bytes
File CKERMIT2.UPD, Supplement to "Using C-Kermit", Second Edition  -*- text -*-

  D R A F T

As of C-Kermit version:  6.1.193 Beta.05
This file last updated:  Thu May  7 11:15:44 1998

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:  kermit-support@columbia.edu
Web:     http://www.columbia.edu/kermit/
Or:      http://kermit-project.org/

NOTICES:

This document:
  Copyright (C) 1997, 1998, Frank da Cruz and Christine M. Gianone.
  All rights reserved.

Kermit 95:
  Copyright (C) 1997, 1998, Trustees of Columbia University in the City of
  New York.  All rights reserved.

C-Kermit:
  Copyright (C) 1985, 1998, Trustees of Columbia University in the City of 
  New York.  The C-Kermit software may not be, in whole or in part, licensed 
  or sold for profit as a software product itself, nor may it be included in or
  distributed with commercial products or otherwise distributed by commercial
  concerns to their clients or customers without written permission of the
  Kermit Project, Columbia University.  This copyright notice must not be
  removed, altered, or obscured.

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

For the full text of the third-party copyright notices, see Appendix V.

------------------------------
WHAT IS IN THIS FILE

This file lists changes made to C-Kermit since the second edition of the book
"Using C-Kermit" was published and C-Kermit 6.0 was released in November
1996.  Use this file as a supplement to the second edition of "Using
C-Kermit".  If the "most recent update" shown above is long ago, contact
Columbia University to see if there is a newer release.

For further information, also see the CKERMIT.BWR ("C-Kermit beware") file for
hints, tips, tricks, restrictions, frequently asked questions, etc, plus the
system-specific "beware file", e.g. CKUKER.BWR for UNIX, CKVKER.BWR for VMS,
etc, and also any system-specific update files such as BUGS.TXT and
UPDATES.TXT for Kermit 95.

---------------
ABOUT FILENAMES

In this document, filenames are generally shown in uppercase (as they are just
above), but on file systems with case-sensitive names such as UNIX, OS-9, and
AOS/VS, lowercase names are used: ckermit.bwr, ckermit2.upd, etc.

-----------------------
NOTE TO KERMIT 95 USERS

This file concentrates on the aspects of C-Kermit that are common to all
versions: UNIX, VMS, VOS, AOS/VS, etc.  Please refer to your Kermit 95
documentation: the "Kermit 95" booklet, the UPDATES.TXT and BUGS.TXT files,
and to all the other files in the Kermit 95 DOCS directory for information
that is specific to Kermit 95.

-------------------------------------
C-KERMIT VERSIONS AND VERSION NUMBERS

"C-Kermit" refers to all the many programs that are compiled in whole or in
part from common C-language source code, comprising:

 . A Kermit file transfer protocol module
 . A command parser and script execution module
 . A modem-dialing module
 . A network support module
 . A character-set translation module.

and several others.  These "system-independent" modules are combined with
system-dependent modules for each platform to provide the required
input/output functions, and also in some cases overlaid with an alternative
user interface, such as Macintosh Kermit's point-and-click interface, and in
some cases also a terminal emulator, as Kermit 95.

The C-Kermit version number started as 1.0, ... 3.0, 4.0, 4.1 and then
(because of confusion at the time with Berkeley UNIX 4.2), 4B, 4C, and so on,
with the specific edit number in parentheses, for example 4E(072) or 5A(188).
This scheme was used through 5A(191), but now we have gone back to the
traditional numbering scheme with decimal points:  major.minor.edit; for
example 6.1.193.  Internal version numbers (the \v(version) variable),
however, are compatible in C-Kermit 5A upwards.

Meanwhile, C-Kermit derivatives for some platforms (Windows, Macintosh) might
go through several releases while C-Kermit itself remains the same.  These
versions have their own platform-specific version numbers, such as Kermit 95
1.1.1, 1.1.2, and so on.

------------------------------
CONTENTS

 I.  C-KERMIT DOCUMENTATION: Information about the C-Kermit manual

 II. NEW FEATURES: Documentation for Features Added Since C-Kermit 6.0

     (1) PROGRAM MANAGEMENT
         1.0.  Bug fixes
         1.1.  Command Continuation
         1.2.  Editor Interface
         1.3.  Web Browser Interface
         1.4.  Editing Commands
         1.5.  Command Switches
               1.5.1. General Switch Syntax
               1.5.2. Order of Switches
               1.5.3. Distinguishing Switches from Other Fields
         1.6.  Dates and Times
         1.7.  Partial Completion of Keywords
         1.8.  Command Recall
         1.9.  EXIT Messages
         1.10. Managing Keyboard Interruptions
         1.11. Taming the Wild Backslash - Part Deux
	       1.11.1. Background
	       1.11.2. Kermit's Quoting Rules
               1.11.3. Passing DOS Filenames from Kermit to Shell Commands
	       1.11.4. Using Variables to Hold DOS Filenames
	       1.11.5. Passing DOS Filenames as Parameters to Macros
	       1.11.6. Passing DOS File Names from Macro Parameters to 
                       the DOS Shell
     (2) MAKING AND USING CONNECTIONS
         2.0. SET LINE and SET HOST Command Switches
	 2.1. Dialing
	      2.1.1. The Dial Result Message
	      2.1.2. Long-Distance Dialing Changes
	      2.1.3. Forcing Long-Distance Dialing
	      2.1.4. Exchange-Specific Dialing Decisions
	      2.1.5. Cautions about Cheapest-First Dialing
	      2.1.6. Blind Dialing (Dialing with No Dialtone)
              2.1.7. Trimming the Dialing Dialog
              2.1.8. Controlling the Dialing Speed
	 2.2. Modems
	      2.2.1. New Modem Types
	      2.2.2. New Modem Controls
	 2.3. TELNET and RLOGIN
              2.3.0. Bug Fixes
	      2.3.1. Telnet Binary Mode Bug Adjustments
	      2.3.2. VMS UCX Telnet Port Bug Adjustment
	      2.3.3. Telnet New Environment Option
	      2.3.4. Telnet Location Option
              2.3.5. Connecting to Raw TCP Sockets
              2.3.6. Incoming TCP Connections
	 2.4. The EIGHTBIT Command
	 2.5. The Services Directory
         2.6. Closing Connections
	 2.7. Using C-Kermit with External Communication Programs
	      2.7.1. C-Kermit over Telnet
	      2.7.2. C-Kermit over Rlogin
              2.7.4. C-Kermit over Serial Communication Programs
	      2.7.4. C-Kermit over Secure Network Clients
	      2.7.4.1. SSH
	      2.7.4.2. SSL
	      2.7.4.3. SRP
	      2.7.4.4. SOCKS
              2.7.4.5. Kerberos and SRP
	      2.7.4.6. FTP
         2.8. Scripting Local Programs
         2.9. X.25 Networking
              2.9.1. IBM AIXLink/X.25 Network Provider Interface for AIX
              2.9.2. HP-UX X.25
     (3) TERMINAL CONNECTION
         3.1. CONNECT Command Switches
         3.2. Triggers
     (4) FILE TRANSFER AND MANAGEMENT
         4.0. Bug Fixes and Minor Changes
	 4.1. File-Transfer Filename Templates
	 4.2. File-Transfer Pipes and Filters
         4.2.1. Introduction
	 4.2.1.1. Terminology
	 4.2.1.2. Notation
	 4.2.1.3. Security
	 4.2.2. Commands for Transferring from and to Pipes
	 4.2.2.1. Sending from a Command
	 4.2.2.2. Receiving to a Command
	 4.2.3. Using File-Transfer Filters
	 4.2.3.1. The SEND Filter 
	 4.2.3.2. The RECEIVE Filter
	 4.2.4. Implicit Use of Pipes
	 4.2.5. Success and Failure of Piped Commands
         4.2.6. Cautions about Using Pipes to Transfer Directory Trees 
	 4.2.7. Pipes and Encryption
         4.2.8. Commands and Functions Related to Pipes
	 4.2.8.1. The OPEN !READ and OPEN !WRITE Commands
	 4.2.8.2. The REDIRECT Command
         4.2.8.3. Receiving Mail and Print Jobs
	 4.2.8.4. Pipe-Related Functions
         4.3. Automatic Per-File Text/Binary Mode Switching
	 4.3.1. Exceptions
	 4.3.2. Overview
	 4.3.3. Commands
	 4.3.4. Examples
         4.4. File Permissions
	 4.4.1. Inherited from Old Files
	 4.4.2. Set from Incoming File
         4.5. File Management Commands
         4.5.1. The DIRECTORY Command
         4.5.2. The CD and BACK Commands
         4.5.2.1. Parsing Improvements
         4.5.2.2. The CDPATH
         4.6. Starting the Remote Kermit Server Automatically    
         4.7. File-Transfer Command Switches
         4.7.1. SEND Command Switches
         4.7.2. GET Command Switches
         4.7.3. RECEIVE Command Switches
         4.8. Kermit Protocol Improvements
	 4.8.1. Multiple Attribute Packets
	 4.8.2. Very Short Packets
         4.9. Wildcard / File Group Expansion
         4.10. Additional Pathname Controls
         4.11. Recursive SEND: Sending directory trees
	 4.11.1. Command-Line Options
	 4.11.2. The SEND /RECURSIVE Command
	 4.11.3. New and Changed Functions
	 4.11.4. Moving Directory Trees Between Like Systems
	 4.11.6. Moving Directory Trees Between Unlike Systems
         4.12. Where Did My File Go?
         4.13. File Output Buffer Control
         4.14. Improved Responsiveness
         4.15. Doubling and Ignoring Characters for Transparency
         4.16. New File-Transfer Display Formats
         4.17. New Transaction Log Format
         4.18. Unprefixing NUL
         4.19. Clear-Channel Protocol
         4.20. Streaming Protocol
	 4.20.1. Commands for Streaming
	 4.20.2. Examples of Streaming
	 4.20.2.1. Streaming on Socket-to-Socket Connections
	 4.20.2.2. Streaming on Telnet Connections
         4.20.2.3. Streaming with Limited Packet Length
         4.20.2.4. Streaming on Dialup Connections
         4.20.2.5. Streaming on X.25 Connections
         4.20.3. Streaming Benchmarks
         4.21. The TRANSMIT Command
     (5) CLIENT/SERVER
         5.0. Hints.
	 5.1. New Command-Line Options
	 5.2. New Client Commands
	 5.3. New Server Capabilities
         5.4. Syntax for Remote Filenames with Embedded Spaces
     (6) INTERNATIONAL CHARACTER SETS
         6.1. The HP-Roman8 Character Set
         6.2. Greek Character Sets
     (7) SCRIPT PROGRAMMING
         7.0. Bug Fixes
         7.1. INPUT Command Details
	 7.2. New or Improved Built-In Variables
	 7.3. New or Improved Built-In Functions
         7.4. New IF Commands
         7.5. Using More than Ten Macro Arguments
         7.6. Clarification of Function Call Syntax
         7.7. Autodownload during INPUT Command Execution
         7.8. Built-in Help for Functions.
         7.9. Arrays
 	 7.9.1. Array Initializers
	 7.9.2. Converting a String into an Array of Words 
	 7.9.3. Automatic Arrays
         7.10. Assignment Operators
         7.11. New OUTPUT Command Options
         7.12. Function and Variable Diagnostics
     (8) USING OTHER FILE TRANSFER PROTOCOLS
     (9) COMMAND-LINE OPTIONS
	 9.1. Command Line Personalities
	 9.2. Built-in Help for Command Line Options
	 9.3. New Command-Line Options
III. APPENDICES  

III.1. Character Set Tables
III.1.1. The Hewlett Packard Roman8 Character Set
III.1.2. Greek Character Sets
III.1.2.1. The ISO 8859-7 Latin / Greek Alphabet
III.1.2.2. The ELOT 927 Character Set
III.1.2.3. PC Code Page 869
III.2. Updated Country Codes

IV. ERRATA & CORRIGENDA: Corrections to "Using C-Kermit" 2nd Edition.
V. ADDITIONAL COPYRIGHT NOTICES

------------------------------
I. C-KERMIT DOCUMENTATION

The user manual for C-Kermit is:

  Frank da Cruz and Christine M. Gianone, "Using C-Kermit", Second Edition,
  Digital Press /  Butterworth-Heinemann, Woburn, MA, 1997, 622 pages,
  ISBN 1-55558-164-1.

This document is a supplement to "Using C-Kermit" 2nd Ed, not a replacement
for it.

  US single-copy price: $39.95; quantity discounts available.  Available in
  computer bookstores or directly from Columbia University:

    The Kermit Project
    Columbia University
    612 West 115th Street
    New York NY  10025-7799
    USA
    Telephone: +1 (212) 854-3703
    Fax:       +1 (212) 663-8202

  Domestic and overseas orders accepted.  Price: US $39.95 (US, Canada, and
  Mexico), $50 elsewhere.  Orders may be paid by MasterCard or Visa, or
  prepaid by check in US dollars.  Add $35 bank fee for checks not drawn on
  a US bank.  Price includes shipping.  Do not include sales tax.
  Inquire about quantity discounts.

  You can also order by phone from the publisher, Digital Press /
  Butterworth-Heinemann, with MasterCard, Visa, or American Express:

    +1 800 366-2665   (Woburn, Massachusetts office for USA & Canada)
    +44 1865 314627   (Oxford, England distribution centre for UK & Europe)
    +61 03 9245 7111  (Melbourne, Vic, office for Australia & NZ)
    +65 356-1968      (Singapore office for Asia) 
    +27 (31) 2683111  (Durban office for South Africa)

  A German-language edition of the First Edition is also available:

    Frank da Cruz and Christine M. Gianone, "C-Kermit - Einfuehrung und
    Referenz", Verlag Heinz Heise, Hannover, Germany (1994).
    ISBN 3-88229-023-4.  Deutsch von Gisbert W. Selke.  Price: DM 88,00.  
    Verlag Heinz Heise GmbH & Co. KG, Helstorfer Strasse 7, D-30625 Hannover.
    Tel. +49 (05 11) 53 52-0, Fax. +49 (05 11) 53 52-1 29.

The Kermit file transfer protocol is specified in:

  Frank da Cruz, "Kermit, A File Transfer Protocol", Digital Press,
  Bedford, MA, 1987, 379 pages, ISBN 0-932376-88-6.
  US single-copy price: $32.95.  Availability as above.

Kermit for Windows 95 is documented in:

  Christine M. Gianone and Frank da Cruz, "Kermit 95",
  Manning Publications, Greenwich CT (1996), 88 pages, ISBN 1-884777-14-7.
  US single-copy price: $14.95.  Included in Kermit 95 shrink wrapped
  package and available separately from Columbia University or direct
  from the publisher:

    Manning Publications Co.
    3 Lewis Street
    Greenwich CT  06830
    USA
    Fax:   +1 (203) 661 9018
    Email: 73150.1431@compuserve.com

News and articles about Kermit software and protocol are published
periodically in the journal, Kermit News.  Subscriptions are free; contact
Columbia University at the address above.

Online news about Kermit is published in the comp.protocols.kermit.announce
and comp.protocols.kermit.misc newsgroups.

------------------------------
II. NEW FEATURES

Support for the Bell Labs Plan 9 operating system was added to version 6.0 
too late to be mentioned in the book (although it does appear on the cover).

Specific items below are grouped together by major topic, roughly
corresponding to the chapters of "Using C-Kermit".

(1) PROGRAM MANAGEMENT AND COMMANDS

1.0. Bug Fixes

The following patches were issued to correct bugs in C-Kermit 6.0.  These are
described in detail in the 6.0 PATCHES file.  All of these fixes have been
made to C-Kermit 6.1.

 0001   All UNIX         C-Kermit mishandles timestamps on files before 1970
 0002	Solaris 2.5++    Compilation error on Solaris 2.5 with Pro C
 0003	All VMS          CKERMIT.INI Fix for VMS
 0004	VMS/VAX/UCX 2.0  C-Kermit 6.0 can't TELNET on VAX/VMS with UCX 2.0
 0005	All              C-Kermit Might Send Packets Outside Window
 0006	All              MOVE from SEND-LIST does not delete original files
 0007	Solaris 2.5++    Higher serial speeds on Solaris 2.5
 0008   All              C-Kermit application file name can't contain spaces
 0009   AT&T 7300 UNIXPC setuid and hardware flow-control problems
 0010   Linux on Alpha   Patch to make ckutio.c compile on Linux/Alpha
 0011   OS-9/68000 2.4   Patch to make ck9con.c compile on OS-9/68000 2.4
 0012   MW Coherent 4.2  Patches for successful build on Coherent 4.2
 0013   SINIX-Y 5.43     "delay" variable conflicts with <sys/clock.h>
 0014   VMS/VAX/CMU-IP   Subject: Patches for VAX/VMS 5.x + CMU-IP
 0015   All              XECHO doesn't flush its output
 0016   VMS              CD and other directory operations might not work
 0017   Linux 1.2.x++    Use standard POSIX interface for high serial speeds
 0018   UNIX             SET WILDCARD-EXPANSION SHELL dumps core
 0019   All              Hayes V.34 modem init string problem
 0020   All              READ command does not fail if file not open
 0021   All              Problems with long function arguments 
 0022   All              Certain \function()s can misbehave
 0023   All              X MOD 0 crashes program
 0024   All              Internal bulletproofing for lower() function
 0025   OpenBSD          Real OpenBSD support for C-Kermit 6.0
 0026   All              Incorrect checks for macro/command-file nesting depth
 0027   All              ANSWER doesn't automatically CONNECT
 0028   All              Overzealous EXIT warning
 0029   All              OUTPUT doesn't echo when DUPLEX is HALF
 0030   All              Minor problems with REMOTE DIRECTORY/DELETE/etc
 0031   All              CHECK command broken
 0032   All              Problem with SET TRANSMIT ECHO
 0033   UNIX, VMS, etc   HELP SET SERVER says too much
 0034   All              READ and !READ too picky about line terminators
 0035   All              END from inside SWITCH doesn't work
 0036   All              Problem telnetting to multihomed hosts
 0037   All              Redirection failures in REMOTE xxx > file 

REDIRECT was missing in many UNIX C-Kermit implementations; in version 6.1, 
it should be available in all of them.

1.1. Command Continuation

Comments that start with ";" or "#" can no longer be continued.  In:

  ; this is a comment -
  echo blah

the ECHO command will execute, rather than being taken as a continuation of
the preceding comment line.  This allows easy "commenting out" of commands
from macro definitions.

However, the text of the COMMENT command can still be continued onto
subsequent lines:

  comment this is a comment -
  echo blah

As of version 6.0, backslash is no longer a valid continuation character.
Only hyphen should be used for command continuation.  This is to make it
possible to issue commands like "cd a:\" on DOS-like systems.

As of version 6.1:

 . You can quote a final dash to prevent it from being a continuation
   character:

      echo foo\-

   This prints "foo-".  The command is not continued.

 . You can enter commands such as:

     echo foo - ; this is a comment

   interactively and they will be properly treated as continued commands.
   Previously this worked only in command files.

1.2. Editor Interface

SET EDITOR <name> [ <options> ]
  Lets you specify a text-editing program.  The <name> can be a fully
  specified pathname like /usr/local/bin/emacs19/emacs, or it can be the
  name of any program in your PATH, e.g. "set editor emacs".  In VMS, it
  must be a DCL command like "edit", "edit/tpu", "emacs", etc.  If an
  environment variable EDITOR is defined when Kermit starts, its value is
  the default editor.  You can also specify options to be included on the
  editor command line.  Returns to Kermit when the editor exits.

EDIT [ <filename> ]
  If the EDIT command is given without a filename, then if a previous filename
  had been given to an EDIT command, it is used; if not, the editor is started
  without a file.  If a filename is given, the editor is started on that file,
  and the filename is remembered for subsequent EDIT commands.

SHOW EDITOR  
  Displays the full pathname of your text editor, if any, along with any
  command line options, and the file most recently edited (and therefore the
  default filename for your next EDIT command).

Related variables: \v(editor), \v(editopts), \v(editfile).

1.3. Web Browser and FTP Interface

C-Kermit includes an FTP command, which simply runs the FTP program; C-Kermit
does not include any built-in support for Internet File Transfer Protocol,
nor any method for interacting directly with an FTP server.  In version 6.1,
however, C-Kermit lets you specify your FTP client:

  SET FTP-CLIENT [ <name> [ <options ] ]

The name is the name of the FTP executable.  In UNIX, Windows, or OS/2, it 
can be the filename of any executable program in your PATH (e.g. "ftp.exe" in
Windows, "ftp" in UNIX); elsewhere (or if you do not have a PATH definition),
it must be the fully specified pathname of the FTP program.  If the name
contains any spaces, enclose it braces.  Include any options after the
filename; these depend the particular ftp client.

The Web browser interface is covered in the following subsections.

1.3.1. Invoking your Browser from C-Kermit

BROWSE [ <url> ]
  Starts your preferred Web browser on the URL, if one is given, otherwise 
  on the most recently given URL, if any.  Returns to Kermit when the browser
  exits.

SET BROWSER [ <name> [ <options> ]
  Use this command to specify the name of your Web browser program, for
  example: "set browser lynx".  The <name> must be in your PATH, or else
  it must be a fully specified filename; in VMS it must be a DCL command.

SHOW BROWSER
  Displays the current browser, options, and most recent URL.

Related variables: \v(browser), \v(browsopts), \v(browsurl).

1.3.2. Invoking C-Kermit from your Browser

The method for doing this depends, of course, on your browser.  Here are
some examples:

Netscape on UNIX (X-based):
  In the Options->Applications section, set your Telnet application to:

    xterm -e /usr/local/bin/kermit/kermit -J %h %p

  (replace "/usr/local/bin/kermit/kermit" by C-Kermit's actual pathname).
  -J is C-Kermit's command-line option to "be like Telnet"; %h and %p are
  Netscape placeholders for hostname and port.

Lynx:
  As far as we know, this can be done only at compile time.  Add the 
  following line to the Lynx userdefs.h file before building the Lynx binary:

#define TELNET_COMMAND "/opt/bin/kermit -J"

  And then add lines like the following to the Lynx.cfg file:

DOWNLOADER:Kermit binary download:/opt/bin/kermit -i -V -s %s -a %s:TRUE
DOWNLOADER:Kermit text download:/opt/bin/kermit -s %s -a %s:TRUE
UPLOADER:Kermit binary upload:/opt/bin/kermit -i -r -a %s:TRUE
UPLOADER:Kermit text upload:/opt/bin/kermit -r -a %s:TRUE
UPLOADER:Kermit text get:/opt/bin/kermit -g %s:TRUE
UPLOADER:Kermit binary get:/opt/bin/kermit -ig %s:TRUE

1.4. Editing Commands

Ctrl-W ("Word delete") was changed in 6.1 to delete back to the previous
non-alphanumeric, rather than all the way back to the previous space.

1.5. Command Switches

As of 6.1, C-Kermit's command parser supports a new type of field, called
a "switch".  This is an optional command modifier.

1.5.1. General Switch Syntax

A switch is a keyword beginning with a slash (/).  If it takes a value, then
the value is appended to it (with no intervening spaces), separated by a colon
(:) or equal sign (=).  Depending on the switch, the value may be a number,
a keyword, a filename, a date/time, etc.  Examples:

  send oofa.txt                              ; No switches
  send /binary oofa.zip                      ; A switch without a value
  send /protocol:zmodem oofa.zip             ; A switch with a value (:)
  send /protocol=zmodem oofa.zip             ; A switch with a value (=)
  send /text /delete /as-name:x.x oofa.txt   ; Several switches

Like other command fields, switches are separated from other fields, and from
each other, by whitespace, as shown in the examples just above.  You can not
put them together like so:

  send/text/delete/as-name:x.x oofa.txt

(as you might do in VMS or DOS, or as we might once have done in TOPS-10 or
TOPS0-20, or PIP).  This is primarily due to ambiguity between "/" as switch
introducer versus "/" as UNIX directory separator; e.g. in:

  send /delete/as-name:foo/text oofa.txt

Does "foo/text" mean the filename is "foo" and the transfer is to be in
text mode, or does it mean the filename is "foo/text"?  Therefore we require
whitespace between switches to resolve the ambiguity.  (That's only one of
several possible ambiguities -- it is also conceivable that a file called
"text" exists in the path "/delete/as-name:foo/").

In general, if a switch can take a value, but you omit it, then either a
reasonable default value is supplied, or an error message is printed:

  send /print:-Plaserwriter oofa.txt         ; Value included = print options
  send /print oofa.txt                       ; Value omitted, OK
  send /mail:kermit@columbia.edu oofa.txt    ; Value included = address
  send /mail oofa.txt                        ; Not OK - address required
  ?Address required

Context-sensitive help (?) and completion (Esc or Tab) are available in the
normal manner:

  C-Kermit> send /pr? Switch, one of the following:
    /print /protocol
  C-Kermit> send /pro<ESC>tocol:?  File-transfer protocol,
   one of the following:
    kermit   xmodem   ymodem   ymodem-g   zmodem
  C-Kermit> send /protocol:k<TAB>ermit

If a switch takes a value and you use completion on it, a colon (:) is printed
at the end of its name to indicate this.  If it does not take a value, a space
is printed.

1.5.2. Order of Switches

The order of switches should not matter, except that they are evaluated from
left to right, so if you give two switches with opposite effects, the
rightmost one is used:

  send /text /binary oofa.zip                ; Sends oofa.zip in binary mode.

1.5.3. Distinguishing Switches from Other Fields

All switches are optional.  A command that uses switches lets you give any
number of them, including none at all.  Example:

  send /binary oofa.zip
  send /bin /delete oofa.zip
  send /bin /as-name:mupeen.zip oofa.zip
  send oofa.zip

But how does Kermit know when the first "non-switch" is given?  It has been
told to look for both a switch and for something else, the data type of the
next field (filename, number, etc).  In most cases, this works well.  But
conflicts are not impossible.  Suppose, for example, in UNIX there was a file
named "text" in the top-level directory.  The command to send it would be:

  send /text

But C-Kermit would think this was the "/text" switch.  To resolve the
conflict, use braces:

  send {/text}

or other circumlocutions such as "send //text", "send /./text", etc.    

The opposite problem can occur if you give an illegal switch that happens
to match a directory name.  For example:

  send /f oofa.txt

There is no "/f" switch (there are several switches that begin with "/f",
so "/f" is ambiguous).  Now suppose there is an "f" directory in the root
directory; then this command would be interpreted as:

  Send all the files in the "/f" directory,
  giving each one an as-name of "oofa.txt".

This could be a mistake, or it could be exactly what you intended; C-Kermit
has no way of telling the difference.  To avoid situations like this, spell
switches out in full until you are comfortable enough with them to know the
minimum abbreviation for each one.  Hint: use ? and completion while typing
switches to obtain the necessary feedback.

1.6. Dates and Times

Some commands and switches take date-time values, such as:

  send /after:{8-Feb-1998 10:28:01}

Various date-time formats are acceptable.  The rules for the date are:

 . The year must be 4 digits (the Millenium is coming!)
 . If the year comes first, the second field is the month.
 . The day, month, and year may be separated by spaces, /, -, or underscore.
 . The month may be numeric (1 = January) or spelled out or abbreviated in
   English.

If the date-time string contains any spaces, it must be enclosed in braces.
Examples of legal dates:
                           Interpretation:
  1998-Feb-8                8 February 1998
  {1998 Feb 8}              8 February 1998
  1998/Feb/8                8 February 1998
  1998_Feb_8                8 February 1998
  1998-2-8                  8 February 1998
  1998-02-08                8 February 1998
  8-Feb-1998                8 February 1998
  08-Feb-1998               8 February 1998
  12/25/1998                25 December 1998
  25/12/1998                25 December 1998

The last two examples show that when the year comes last, and the month is
given numerically, the order of the day and month doesn't matter as long as
the day is 13 or greater (mm/dd/yyyy is commonly used in the USA, whereas
dd/mm/yyyy is the norm in Europe).  However:

  08/02/1998                Is ambiguous and therefore not accepted.

If a date is given, the time is optional and defaults to 00:00:00.  If the
time is given with a date, it must follow the date, separated by space, /, -,
or underscore, and with hours, minutes, and seconds separated by colon (:).
Example:

  1998-Feb-8 10:28:01       8 February 1998, 10:28:01am

If a date is not given, the current date is used and a time is required.

Time format is hh:mm:ss or hh:mm or hh in 24-hour format, or followed by "am"
or "pm" (or "AM" or "PM") to indicate morning or afternoon.  Examples of legal
times:
                           Interpretation:
  3:23:56                    3:23:56am
  3:23:56am                  3:23:56am
  3:23:56pm                  3:23:56pm = 15:23:56
  3:23pm                     3:23:00pm = 15:23:00
  3:23PM                     3:23:00pm = 15:23:00
  3pm                        3:00:00pm = 15:00:00

Examples of legal date-times:

  send /after:{8 Feb 1998 10:28:01}
  send /after:8_Feb_1998_10:28:01
  send /after:8-Feb-1998/10:28:01
  send /after:1998/02/08/10:28:01
  send /after:1998/02/08_10:28:01
  send /after:1998/02/08_10:28:01am
  send /after:1998/02/08_10:28:01pm
  send /after:1998/02/08_10:28pm
  send /after:1998/02/08_10pm
  send /after:10:00:00pm
  send /after:10:00pm
  send /after:10pm
  send /after:22

Finally, there is a special all-numeric format you can use:

  yyyymmdd hh:mm:ss

For example:

  19980208 10:28:01

There are no optional parts to this format and it must be exactly 17
characters long, punctuated as shown.  This is the format returned by
\fdate(filename), so you can also use constructions like this:

  send /after:\fdate(oofa.txt)

which means "all files newer than oofa.txt".

1.7. Partial Completion of Keywords

Partial completion of keywords was added in 6.1.  In prior versions, if
completion was attempted (by pressing the Esc or Tab key) on a string that
matched different keywords, you'd just get a beep.  Now Kermit completes up to
the first character where the possibly matching keywords differ and then
beeps.  For example:

  send /n<Tab>

which matches /NOT-BEFORE and /NOT-AFTER, now completes up to the dash:

  send /n<Tab>ot-<Beep>

Partial completion works for filenames too (as it has for some years).

1.8. Command Recall

C-Kermit has had a command history buffer for some time, which could be
scrolled interactively using control characters or (in Kermit 95 only) arrow
keys.  Version 6.1 adds a REDO command that allows the most recent command
matching a given pattern to be re-executed:

{ REDO, RR, ^ } [ <pattern> ]
  Search the command history list for the most recent command that matches
  the given pattern, and if one is found, execute it again.

The pattern can be a simple string (like "send"), in which case the last SEND
command is re-executed.  Or it can contain wildcard characters "*" and/or "?",
which match any string and any single character, respectively (note that "?"
must be preceded by backslash to override its normal function of giving help).

The match works by appending "*" to the end of the given pattern (if you
didn't put one there yourself).  Thus "redo *oofa" becomes "redo *oofa*" and
therefore matches the most recent command that contains "oofa" anywhere within
the command.  If you want to inhibit the application of the trailing "*",
e.g. to force matching a string at the end of a command, enclose the pattern
in braces:

  redo {*oofa}

matches the most recent command that ends with "oofa".

REDO commands themselves are not entered into the command history list.  If no
pattern is given, the previous (non-REDO) command is re-executed.  The REDOne
command is reinserted at the end of the command history buffer, so the command
scrollback character (Ctrl-P, Ctrl-B, or Uparrow) can retrieve it.

Examples:

  C-Kermit>echo foo
  foo
  C-Kermit>show alarm
  (no alarm set)
  C-Kermit>echo blah
  blah
  C-Kermit>redo          ; Most recent command
  blah
  C-Kermit>redo s        ; Most recent command starting with "s"
  (no alarm set)
  C-Kermit>redo echo f   ; Most recent command starting with "echo f"
  foo
  C-Kermit>redo *foo     ; Most recent command that has "foo" in it
  foo
  C-Kermit><Ctrl-P>      ; Scroll back
  C-Kermit>echo foo      ; The REDOne command is there
  C-Kermit>redo {*foo}   ; Most recent command that ends with "foo"
  foo
  C-Kermit>

Since REDO, REDIAL, and REDIRECT all start the same way, and RED is the
designated non-unique abbreviation for REDIAL, REDO must be spelled out in
full.  For convenience, RR is included as an invisible easy-to-type synonym
for REDO.  You can also use the "^" character for this:

  C-Kermit>^             ; Most recent command
  C-Kermit>^ s           ; Most recent command starting with "s"
  C-Kermit>^s            ; Ditto (space not required after "^").
  C-Kermit>^*foo         ; Most recent command that has "foo" in it.
  C-Kermit>^{*foo}       ; Most recent command ends with "foo".

Unlike the manual command-history-scrolling keys, the REDO command can be
used in a script, but it's not recommended (since the command to be REDOne
might not be found, so if the REDO command fails, you can't tell whether it
was because REDO failed to find the requested command, or because the command
was found but it failed).

1.9. EXIT Messages

The EXIT and QUIT commands now accept an optional message to be printed.
This makes the syntax of EXIT and QUIT just like END and STOP:

  { EXIT, QUIT, END, STOP } [ <status-code> [ <message> ] ]

where <status-code> is a number (0 indicating success, nonzero indicating
failure).  This is handy in scripts that are never supposed to enter
interactive mode:

  dial 7654321
  if fail exit 1 Can't make connection - try again later.

Previously this could only be done in two steps:

  dial 7654321
  xif fail { echo Can't make connection - try again later, exit 1 }

A status code must be included in order to specify a message.  In the case 
of EXIT and QUIT, the default status code is contained in the variable
\v(exitstatus), and is set automatically by various events (file transfer
failures, etc; it can also be set explicitly with the SET EXIT STATUS
command).  If you want to give an EXIT or QUIT command with a message, but
without changing the exit status from what it normally would have been, use
the \v(exitstatus) variable, e.g.:

   exit \v(existatus) Goodbye from \v(cmdfile).

The EXIT status is returned to the system shell or whatever other process
invoked C-Kermit, e.g. in UNIX:

  C-Kermit> exit 97 bye bye
  bye bye
  $ echo $?
  97
  $
 
1.10. Managing Keyboard Interruptions

When C-Kermit is in command or file-transfer mode (as opposed to CONNECT
mode), it can be interrupted with Ctrl-C.  Version 6.1 adds the ability to
disarm the Ctrl-C interrupt:

SET COMMAND INTERRUPT { ON, OFF }
  COMMAND INTERRUPT is ON by default, meaning the Ctrl-C can be used to
  interrupt a command or a file transfer in progress.  Use OFF to disable
  these interruptions, and use it with great caution for obvious reasons.
  
Several other commands can be interrupted by pressing any key while they are
active.  Version 6.1 adds the ability to disable this form of interruption
also:

SET INPUT CANCELLATION { ON, OFF }
  Whether an INPUT command in progress can be interrupted by pressing a key.
  Normally ON.  Setting INPUT CANCELLATION OFF makes INPUT commands
  uninterruptible except by Ctrl-C (unless COMMAND INTERRUPTION is also OFF).

SET SLEEP CANCELLATION { ON, OFF }
  Whether a SLEEP, PAUSE, or WAIT command in progress can be interrupted by
  pressing a key.  Normally ON.  Setting SLEEP CANCELLATION OFF makes these
  commands uninterruptible except by Ctrl-C (unless COMMAND INTERRUPTION is
  also OFF).  Synonyms: SET PAUSE CANCELLATION, SET WAIT CANCELLATION.

So to make certain a script is not interruptible by the user, include these
commands:

  SET SLEEP CANCELLATION OFF
  SET INPUT CANCELLATION OFF
  SET COMMAND INTERRUPTION OFF

Make sure to turn them back on afterwards.

1.11. Taming The Wild Backslash -- Part Deux

"Using C-Kermit", 2nd Edition, contains a brief section, "Taming the Wild
Backslash", on page 48, which subsequent experience has shown to be inadequate
for Kermit users intent on writing scripts that deal with Windows, DOS, and
OS/2 filenames, in which backslash (\) is used as the directory separator.
This section fills in the blanks.

1.11.1. Background

The Kermit command language shares a certain unavoidable but annoying
characteristic with most other command languages that are capable of string
replacement, namely the necessity to "quote" certain characters when you want
them to be taken literally.  This is a consequence of the facts that:

 a. One or more characters must be set aside to denote replacement, rather
    than acting as literal text.

 b. We have only 96 printable characters to work with in ASCII, which is
    still the only universally portable character set.

 c. There is no single printable character that is unused everywhere.

 d. Variables are not restricted to certain contexts, as they are
    in formal programming languages like C and Fortran, but can appear
    anywhere at all within a command, and therefore require special syntax.

Thus there can be conflicts.  To illustrate, the standard UNIX shell uses 
dollar sign ($) to introduce variables.  So the shell command:

  echo $TERM

displays the value of the TERM variable, e.g. vt320.  But suppose you want to
display a real dollar sign:

  echo The price is $10.20

This causes the shell to evaluate the variable "$1", which might or might not
exist, and substitute its value, e.g.:

  The price is 0.20

(in this case the $1 variable had no value.)  This is probably not what you
wanted.  To force the dollar sign to be taken literally, you must apply a
"quoting rule", such as "precede a character by backslash (\) to force the
shell to take the character literally":

  echo The price is \$10.20
  The price is $10.20

But now suppose you want the backslash AND the dollar sign to be taken
literally:

  echo The price is \\$10.20  

This doesn't work, since the first backslash quotes the second one, thereby 
leaving the dollar sign unquoted again:

  The price is \0.20

Quoting the dollar sign requires addition of a third backslash:

  echo The price is \\\$10.20  
  The price is \$10.20  

The first backslash quotes the second one, and the third backslash quotes
the dollar sign.

Every command language -- all UNIX shells, VMS DCL, DOS Batch, AOS/VS CLI, etc
etc -- has similar rules.  UNIX shell rules are probably the most complicated,
since many printable characters -- not just one -- are special there: dollar
sign, single quote, double quote, backslash, asterisk, accent grave, number
sign, ampersand, question mark, parentheses, brackets, braces, etc --
practically every non-alphanumeric character needs some form of quoting if it
is to be taken literally.  And to add to the confusion, the UNIX shell offers
many forms of quoting, and many alternative UNIX shells are available, each
using slightly different syntax.

1.11.2. Kermit's Quoting Rules

Kermit's basic quoting rules are simple by comparison (there are, of course,
additional syntax requirements for macro definitions, command blocks, function
calls, etc, but they are not relevant here).

The following characters are special in Kermit commands:

Backslash (\)
  Introduces a variable, or the numeric representation of a special character,
  or a function, or other item for substitution.  If the backslash is followed
  by a digit or by any of the following characters:

    x, o, d, m, f, v, $, %, &, {    

  this indicates a special substitution item; otherwise the following
  character is to be taken literally (exceptions: \ at end of line is taken
  literally; \n, \b, and \n are special items in the OUTPUT command only).

Semicolon (;)
  (Only when at the beginning of a line or preceded by at least one space
  or tab)  Introduces a comment.

Number sign (#)
  (Only when at the beginning of a line or preceded by at least one space
  or tab)  Just like semicolon; introduces a comment.

Question mark (?)
  (Only at the command prompt - not in command files or macros)  Requests
  context-sensitive help.

To force Kermit to take any of these characters literally, simply precede it
by a backslash (\).

Sounds easy!  And it is, except when backslash also has a special meaning to
the underlying operating system, as it does in DOS, Windows, and OS/2, where
it serves as the directory separator in filenames such as:

  D:\K95\KEYMAPS\READ.ME

Using our rule, we would need to refer to this file in Kermit commands as
follows:

  D:\\K95\\KEYMAPS\\READ.ME

But this would not be obvious to new users of Kermit software on DOS, Windows,
or OS/2, and it would be annoying to seasoned ones.  Thus MS-DOS Kermit and
Kermit 95 go to rather extreme lengths to allow the more natural notation, as
in: 

  send d:\k95\keymaps\read.me

The reason this is tricky is that we also need to allow for variables and
other expressions introduced by backslash in the same command.  For example,
suppose \%a is a variable whose value is "oofa" (without the quotes).  What
does the following command do?

  send d:\%a

Does it send the file named "oofa" in the current directory of the D: disk, or
does it send a file named "%a" in the root directory of the D: disk?  This is
the kind of trouble we get into when we attempt to bend the rules in the
interest of user friendliness.  (The answer is: if the variable \%a has
definition that is the name of an existing file, that file is sent; if a file
d:\%a exists, it is sent; otherwise if both conditions are true, the variable
takes precedence, and the literal filename can be forced by quoting: \\%a.)

In Kermit 95 (but not MS-DOS Kermit), we also bend the rules another way by
allowing you to use forward slash (/) rather than backslash (\) as the
directory separator:

  send d:/k95/keymaps/read.me

This looks more natural to UNIX users, and in fact is perfectly acceptable to
the Windows 95/98/NT and OS/2 operating systems on the API level.  BUT (there
is always a "but") the Microsoft shell, COMMAND.COM, for Windows 95/98 and NT
does not allow this notation, and therefore it can not be used in any Kermit
command -- such as RUN -- that invokes the Windows command shell AND your
command shell is COMMAND.COM or any other shell that does not allow forward
slash as directory separator (some alternative shells do allow this).

  NOTE: There exists a wide variety of alternative shells from third
  parties that do not have this restriction.  If you are using a shell
  that accepts forward slash as a directory separator, you can stop
  reading right now -- UNLESS (there is always an "unless") you want your
  scripts to be portable to systems that have other shells.  Also note
  that some Windows shells might actually REQUIRE forward slashes
  (instead of backslashes) as directory separators; we do not treat this
  situation below, but the treatment is obvious -- use slash rather 
  backslash as the directory separator.

1.11.3. Passing DOS Filenames from Kermit to Shell Commands

The following Kermit commands invoke the system command shell:

  RUN (and its synonyms ! and @)
  REDIRECT
  PIPE

Each of these commands takes a shell command as an operand.  These shell
commands are not, and can not be, parsed by Kermit since Kermit does not know
the syntax of shell commands, and so can't tell the difference between a
keyword, a filename, a variable, a switch, or other item.  Therefore the rules
can not be bent since Kermit doesn't know where or how to bend them.  To
illustrate (using the regular Windows shell):

  run c:\\windows\\command\\chkdsk.exe 

works OK, but:

  run c:/windows/command/chkdsk.exe 

is not accepted by COMMAND.COM.  But:

  run c:\windows\command\chkdsk.exe 

results in Kermit applying its quoting rules before sending the text to the
shell.  Since "w" and "c" are not in the list of backslash-item codes, the
backslash means "take the following character literally".  Thus, by the
time this filename gets to the Windows shell, it has become:

  c:windowscommandchkdsk.exe 

which is probably not what you wanted.  (If "w" and "c" were in the list,
the results could be even stranger.)  Even more confusing is the case where
a directory or filename starts with one or more digits:

  run c:\123\lotus.exe

in which "\123" is the Kermit notation for ASCII character 123, which happens
to be left brace ({), resulting in "c:{lotus.exe".

So when passing filenames to a Windows shell, always use double backslashes as
directory separators, to ensure that the shell gets single backslashes:

  run c:\\windows\\command\\chkdsk.exe 
  run c:\\123\\lotus.exe

Similar problems might occur with the built-in EDIT, BROWSE, and FTP commands.
These commands result in Kermit building a shell command internally to invoke
the associated helper program; the form of this command might conflict with
the form demanded by certain alternative shells.

1.11.4. Using Variables to Hold DOS Filenames

Now to the next level.  Suppose you want to write a script in which filenames
are parameters, and therefore are stored in variables.  Example:

  define \%f c:\windows\command\chkdsk.exe 
  ...
  run \%f

Obviously this won't work for the reasons just noted; the RUN command requires
directory separators be coded as double backslashes:

  define \%f c:\\windows\\command\\chkdsk.exe 
  ...
  run \%f

This will work; no surprises here.  However, if you had used ASSIGN rather
than DEFINE, you might have been surprised after all; review pages 348-349 of
"Using C-Kermit" (2nd Ed) for the difference between DEFINE and ASSIGN.

We have said that any Kermit 95 or MS-DOS Kermit command that parses filenames
itself -- SEND, for example -- does not require double backslashes since it
knows it is parsing a filename.  So since the following works:

  send c:\windows\command\chkdsk.exe 

Should the following also work?

  define \%f c:\windows\command\chkdsk.exe 
  ...
  send \%f

Answer: No.  Why?  Because \%f is evaluated "recursively", to allow for the
possibility that its definition contains further variable references.  This is
true of all "backslash-percent-letter" (or -digit) variables, and also for
array references.  So \%f becomes c:\windows\command\chkdsk.exe, which
becomes c:windowscommandchkdsk.exe.

The trick here is to use the "other" kind of variable, that is evaluated
only "one level deep" rather than recursively:

  define filename c:\windows\command\chkdsk.exe 
  ...
  send \m(filename)

Similarly if you want to prompt the user for a filename:

  ask filename { Please type a filename: }
   Please type a filename: c:\windows\command\chkdsk.exe
  send \m(filename)

1.11.5. Passing DOS Filenames as Parameters to Macros

Suppose you want to pass a DOS filename containing backslashes as a parameter
to a Kermit macro.  This raises two issues:

 1. Parameters to macros are "just text" and so are fully evaluated before
    they are passed to the macro.

 2. Once inside the macro, the formal parameters \%1, \%2, ... \%9 are the
    type of variable that is evaluated recursively.

Thus a DOS filename is ruined once in the act of parsing the macro invocation,
and again when referring to it from within the macro.  To illustrate, suppose
"test" is a macro.  Then in the invocation:

  test c:\mydir\blah.txt

"c:mydirblah.txt" is assigned to \%1.  However, if we double the backslashes:

  test c:\\mydir\\blah.txt

"c:\mydir\blah.txt" is assigned to \%1.  But then when you refer to \%1 in
the macro, it is evaluated recursively, resulting in "c:mydirblah.txt".
To illustrate:

  define test echo \%1
  test c:\mydir\blah.txt
  c:mydirblah.txt
  test c:\\mydir\\blah.txt
  c:mydirblah.txt
  test c:\\\\mydir\\\\blah.txt
  c:\mydir\blah.txt

Let's address each part of the problem separately.  First, inside the macro.
You can use the \fcontents() function to force a backslash-percent variable
(such as a macro argument) to be evaluated one level deep instead of
recursively, for example:

  define test echo { The filename is "\fcontents(\%1)"}

  test c:\mydir\blah.txt               ; We don't expect this to work
   The filename is "c:mydirblah.txt"   ; and it doesn't.
  test c:\\mydir\\blah.txt             ; But this does...
   The filename is "c:\mydir\blah.txt"

Thus if the filename arrives inside the macro with single backslashes, the
backslashes are preserved if you always refer to the parameter through the
\fcontents() function.

Now how to ensure that backslashes are not stripped or misinterpreted when
passing a filename to a macro?  This brings us back to what we learned in
earlier sections:

 1. If it is a literal filename, either double the backslashes, or (if the
    filename is to be used only within Kermit itself and not passed to a
    DOS shell, or it is to be passed to an alternative shell that accepts
    forward slash as a directory separator), use forward slash instead of
    backslash as the directory separator.

 2. If it is a variable that contains a filename, make sure you use a
    macro-style variable name, rather than a backslash-percent-character
    name.

Examples:

  define test echo \fcontents(\%1)
  define filename c:\mydir\blah.txt

  test c:\\mydir\\blah.txt  ; Literal filename with double backslashes
  c:\mydir\blah.txt

  test c:/mydir/blah.txt    ; Literal filename with forward slashes
  c:/mydir/blah.txt

  test \m(filename)         ; Variable
  c:\mydir\blah.txt

But what if you don't like these rules and you still want to pass a literal
filename containing single backslashes to a macro?  This is possible too, but
a bit tricky: turn command quoting off before invoking the macro, and then
turn it back on inside the macro.  Example:

  define test set command quoting on, echo \fcontents(\%1)

  set command quoting off
  test c:\mydir\blah.txt
  c:\mydir\blah.txt

Upon return from the macro, command quoting is back on (since the macro
turned it on).

Obviously this trick can not be used if the filename is stored in a variable,
since it prevents the variable from being evaluated.

1.11.6. Passing DOS File Names from Macro Parameters to the DOS Shell

Now suppose you need to pass a DOS filename to a macro, and the macro needs
to pass it, in turn, to the Windows shell via (say) Kermit's RUN command.
This works too:

  define xrun run \fcontents(\%1)
  xrun c:\\windows\\command\\chkdsk.exe

(or you can use the SET COMMAND QUOTING OFF / ON technique described above
to avoid the double backslashes.)  But..

  xrun c:/windows/command/chkdsk.exe

does not work if the Windows shell does not recognize "/" as a directory
separator.  If there is a chance that a filename might be passed to the macro
in this form, the macro will need to convert it to a form acceptable to the
shell:

  define xrun run \freplace(\fcontents(\%1),/,\\)

Here we replace all occurrences (if any) of "/" in the argument with "\" prior
to issuing the RUN command.  Of course, in order to specify "\" as a literal
character in the \freplace() argument list, we have to double it.


(2) MAKING AND USING CONNECTIONS

2.0. SET LINE and SET HOST Command Switches

The SET LINE (SET PORT) and SET HOST command now allow switches before the
device or host name, in most cases.  The new syntax is backwards compatible
with the previous syntax; thus SET LINE, SET PORT, and SET HOST commands in
command files written for C-Kermit 6.0 or earlier still work.  The expanded
syntax is:

  SET { LINE, PORT, HOST } [ switch [ switch [ ... ] ] ] <rest-of-command>

The switches are:

/CONNECT
  Enter CONNECT mode immediately and automatically after the device or
  connection is open.  On serial devices, however, when CARRIER-WATCH is
  not OFF, wait up to 1 second for the Carrier Detect signal to appear
  before trying to connect, to give the device time to react DTR, which
  might have been off prior to opening the device.

/SERVER
  Enter server mode immediately and automatically after the device or
  connection is open.  Treatment of carrier is the same as for /CONNECT.
  
/COMMAND
  The "hostname" is really the name of a command to execute, which is used
  to make the connection, such as "cu" or "rlogin", etc.  Explained in
  Section 2.7.

Note: SET HOST switches not available in the RLOGIN and TELNET commands, since
these commands already include an implicit /CONNECT and preclude automatic
entry into server mode.

The /CONNECT and /SERVER switches are especially useful with "set host *"
connections.  For example, suppose you want to start a Kermit server on socket
3000 of your TCP host.  Normally you would have to give the command:

  set host * 3000

and then wait for a connection to come in, and only then could you give the
SERVER command (or else define a macro to do this, and then execute the macro).
Now you can do it in one step:

  set host /server * 3000

This tells C-Kermit to wait for the connection and then enter server mode
once it comes in, no matter how long it takes.  Similarly, "set host /conn *"
can be used to wait for a "chat" connection to come in.

Another set of switches is available in VMS only, for use only with SET LINE:

/SHARE
  Allows the SET LINE device to be opened in shared mode.  Normally it makes
  no sense to open a serial device in shared mode, but it's necessary when
  C-Kermit is running in an environment such as DECIntact, that opens your
  job's controlling terminal in such a way that C-Kermit can't open it too,
  unless it enables SHARE privilege.  Note: SHARE privilege is required.

/NOSHARE
  Requires that the SET LINE device not be in use by any other process in
  order for it to be successfully opened by C-Kermit.  If neither /SHARE nor
  /NOSHARE is specified, /NOSHARE is used.

Additional switches might be added in the future; type "set host ?" or "set
line ?" to see a list of those that are available in your C-Kermit program.

2.1. Dialing

2.1.1. The Dial Result Message

If DIAL DISPLAY is not ON, the "Call complete" message now shows the modem's
call result message, for example:

  Dialing: ...
  Call complete: "CONNECT 31200/ARQ/V32/LAPM/V42BIS"

The exact format and contents of this message, of course, depends on the
make, model, and configuration of your modem, so use your modem manual to
interpret it.  The call result message is also available in C-Kermit's
\v(dialresult) variable.

  C-Kermit> echo \v(dialresult)
  CONNECT 31200/ARQ/V32/LAPM/V42BIS
  C-Kermit> echo Speed = \fword(\v(dialresult),2)
  Speed = 31200
  C-Kermit>

2.1.2. Long-Distance Dialing Changes

Several new dialing features and commands have been added in version 6.1
to address the kinds of changes that are taking place in North America,
France, and elsewhere, for example for 10-digit dialing in North America.

In France, effective 18 October 1996, all calls, even local ones, must be
dialed with an area code.  French area codes are presently 1-digit numbers,
1-6, and the long-distance dialing prefix is 0.  All calls within France are
considered long distance and begin with 01, 02, ..., 06.

Effective 1 May 1997, all calls within the US state of Maryland, even local
ones, must be dialed with an area code but WITHOUT the long-distance prefix --
this is the now widely-known North American phenomenon of "ten digit dialing".
The same is happening elsewhere -- many cities in Florida will adopt 10-digit
dialing in 1998.

C-Kermit 6.0 and Kermit 95 1.1.11 and earlier handle the French situation
via a reasonable subterfuge (setting the local area code to a nonexistent
one), but did not handle "ten-digit dialing" well at all; the recommended
technique was to change the long-distance dialing prefix to nothing, but this
defeated Kermit's "list numbers for one name" feature when the numbers were in
different locations.  For example:

  set dial ld-prefix
  dial oofa

where "oofa" is a dialing directory entry name corresponding to entries that
are in (say) Maryland as well as other states, would not correctly dial the
numbers not in Maryland.

A new command lets you specify a list of area codes to be considered local,
except that the area code must be dialed:

  SET DIAL LC-AREA-CODES [ areacode [ areacode [ areacode [ ... ] ] ] ]

The list may include up to 32 area codes.  If a number is called whose area
code is in this list, it is dialed WITHOUT the long-distance prefix, but WITH
the area code.  So in Maryland, which presently has two area codes, 410 and
301, the setup would be:

  SET DIAL LC-AREA-CODES 410 301

Example:

  SET DIAL LD-PREFIX 1
  SET DIAL AREA-CODE 301
  SET DIAL LC-AREA-CODES 410 301 <-- Area codes in 10-digit dialing region
  DIAL +1 (301) 765-4321         <-- Dials 3017654321  (local with area code)
  DIAL +1 (410) 765-4321         <-- Dials 4107654321  (local with area code)
  DIAL +1 (212) 765-4321         <-- Dials 12127654321 (long distance)

The SET DIAL LC-AREA-CODES command does not replace the SET DIAL AREA-CODE
command.  The latter specifies the area code you are dialing from.  If the
called number is in the same area code, then the area code is dialed if it is
also in the LC-AREA-CODES list, and it is not dialed otherwise.  So if "301"
had not appeared in the LC-AREA-CODES list in the previous example:

  SET DIAL LD-PREFIX 1
  SET DIAL AREA-CODE 301
  SET DIAL LC-AREA-CODES 410     <-- Area codes in 10-digit dialing region
  DIAL +1 (301) 765-4321         <-- Dials 7654321     (local)
  DIAL +1 (410) 765-4321         <-- Dials 4107654321  (local with area code)
  DIAL +1 (212) 765-4321         <-- Dials 12127654321 (long distance)

The new Kermit versions also add a Local Call Prefix and Local Call Suffix, in
case you have any need for it.  These are added to the beginning and of local
phone numbers (i.e. numbers that are not long-distance or international).
Examples:

  SET DIAL LD-PREFIX 1
  SET DIAL LC-PREFIX 9
  SET DIAL LC-SUFFIX *
  SET DIAL LC-AREA-CODES 410     <-- Area codes in 10-digit dialing region
  SET DIAL AREA-CODE 301
  DIAL +1 (301) 765-4321         <-- Dials 97654321*     (local)
  DIAL +1 (410) 765-4321         <-- Dials 94107654321*  (local with area code)
  DIAL +1 (212) 765-4321         <-- Dials 12127654321   (long distance)

2.1.3. Forcing Long-Distance Dialing

Suppose a number is in your country and area, but for some reason you need to
dial it long-distance anyway (as is always the case in France).  There have
always been various ways to handle this:

 1. Temporarily set your area code to a different (or nonexistent or
    impossible) one (but this required knowledge of which area codes were
    nonexistent or impossible in each country).

 2. Dial the number literally instead of using the portable format, but this
    defeats the purpose of the portable dialing directory.

Now there is also a new command that, very simply, can force long-distance
dialing:

SET DIAL FORCE-LONG-DISTANCE { ON, OFF }
  If a call is placed to a portable phone number within the same country
  code as the calling number, it is dialed with the long-distance prefix
  and the area code if FORCE-LONG-DISTANCE is ON.  If OFF, the regular
  rules and procedures apply.

Example (France):

  SET DIAL COUNTRY-CODE 33
  SET DIAL AREA-CODE 6
  SET DIAL FORCE-LONG-DISTANCE ON

(In fact, SET DIAL COUNTRY-CODE 33 automatically sets DIAL FORCE-LONG-DISTANCE
ON...)

Example (USA, for a certain type of reverse-charge calling in which the
called number must always be fully specified):

  SET DIAL PREFIX 18002666328$     ; 1-800-COLLECT
  SET DIAL COUNTRY-CODE 1
  SET DIAL AREA-CODE 212
  SET DIAL FORCE-LONG-DISTANCE ON

Example (Toronto, where calls to exchange 976 within area code 416 must be
dialed as long distance, even when you are dialing from area code 416):

  SET DIAL COUNTRY-CODE 1
  SET DIAL AREA-CODE 416
  SET DIAL FORCE-LONG-DISTANCE ON
  DIAL +1 (416) 976-xxxx

If dialing methods were consistent and sensible, of course it would be
possible to always dial every domestic call as if it were long distance.  But
in many locations this doesn't work or if it does, it costs extra.  The
following macro can be used for dialing with forced long-distance format:

  define LDIAL {
      local \%x
      set dial force-long-distance on
      dial \%*
      asg \%x \v(success)
      set dial force-long-distance off   
      end \%x
  }

2.1.4. Exchange-Specific Dialing Decisions

This applies mainly to the North American Numbering Plan (NANP).  Refer to the
section "Alternative notations" in "Using C-Kermit" 2nd Edition, pages
106-107, and the story about Toronto on page 110.  Using the new LC-AREA-CODES
list, we can address the problem by treating the exchange as part of the area
code:

  SET DIAL LD-PREFIX 1
  SET DIAL AREA-CODE 416
  SET DIAL LC-AREA-CODES 905276
  DIAL +1 416 765 4321               <-- 7654321      (local)
  DIAL +1 905 276 4321               <-- 9052764321   (local with area code)
  DIAL +1 905 528 4321               <-- 19055284321  (long distance)

The same technique can be used in Massachusetts (story at top of page 111)
and in any other place where dialing to some exchanges within a particular
area code is local, but to others in the same area code is long distance.

2.1.5. Cautions about Cheapest-First Dialing

Kermit does not maintain a knowledge base of telephony information; it only
provides the tools to let you enter a phone number in a standard format and
dial it correctly from any location in most cases.

In particular, Kermit does not differentiate the charging method from the
dialing method.  If a call that is DIALED as long-distance (e.g. from 212 to
718 in country code 1) is not CHARGED as long distance, we have no way of
knowing that without keeping a matrix of charging information for every
area-code combination within every country, and any such matrix would be
obsolete five minutes after it was constructed.  Thus, "cheapest-first"
sorting is only as reliable as our assumption that the charging method follows
the dialing method.  A good illustration would be certain online services that
have toll-free dialup numbers which they charge you a premium (in your online
service bill) for using.

2.1.6. Blind Dialing (Dialing with No Dialtone)

C-Kermit's init string for Hayes-like modems generally includes an X4 command
to enable as many result codes as possible, so that Kermit can react
appropriately to different failure reasons.  One of the result codes that X4
enables is "NO DIALTONE".  A perhaps not obvious side effect of enabling this
result code that the modem must hear dialtone before it will dial.

It is becoming increasingly necessary to force a modem to dial even though it
does not hear a dialtone on the phone line; for example, with PBXs that have
strange dialtones, or with phone systems in different countries, or with ISDN
phones, etc.  This is called "blind dialing".

C-Kermit 6.1 has two new commands to cope with this situation:

SET DIAL IGNORE-DIALTONE { ON, OFF }
  OFF (the default) means to tell the modem to wait for dialtone before
  dialing.  ON means to enable "blind dialing", i.e. tell the modem NOT
  to wait for dialtone before dialing.  Generally this is accomplished by
  sending ATX3 to the modem just prior to dialing.  SET MODEM TYPE xxx
  and then SHOW MODEM displays Kermit's built-in "ignore dialtone" command.

SET DIAL COMMAND IGNORE-DIALTONE <text>
  This lets you change the built-in ignore-dialtone command (such as ATX3)
  to whatever you choose, in case the built-in one does not work, or another
  command works better.

Notes:

 1. The ignore-dialtone command is not sent unless SET DIAL IGNORE-DIALTONE
    is ON.

 2. The ATX3 command generally disables not only NO DIALTONE, but also BUSY.
    So this will prevent Kermit from detecting when the line is busy.  This
    is a property of the modem, not of Kermit.

2.1.7. Trimming the Dialing Dialog

The command:

  SET MODEM COMMAND <action> [ <command> ]

is used to override Kermit's built-in modem commands for each action, for
each kind of modem in its internal database.  If you include a <command>,
this is used instead of the built-in one.  If you omit the <command>, this
restores the original built-in command.

If you want to omit the command altogether, so Kermit doesn't send the command
at all, or wait for a response, use:

  SET MODEM COMMAND <action> {}

That is, specify a pair of empty braces as the command, for example:

  SET MODEM COMMAND ERROR-CORRECTION ON {}

2.1.8. Controlling the Dialing Speed

The rate at which characters are sent to the modem during dialing is normally
controlled by the built-in modem database.  You might want to override this
if Kermit seems to be dialing too slowly, or it is sending characters to the
modem faster than the modem handle them.  A new command was added for this
in C-Kermit 6.1:

SET DIAL PACING <number>
  Specifies the number of milliseconds (thousandths of seconds) to pause
  between each character when sending commands to the modem during DIAL or
  ANSWER command execution.  0 means no pause at all, -1 (the default) or any
  other negative number means to use the value from the database.  Any number
  greater than 0 is the number of milliseconds to pause.

HINT: You might also need to control the rate at which the modem generates
Touch Tones during dialing, for example when sending a numeric page.  There
are two ways to do this.  One way is to insert pause characters into the
dialing string.  For modems that use the AT command set, the pause character
is comma (,) and causes a 2-second pause.  On most modems, you can use the S8
register to change the pause interval caused by comma in the dialing string.
The other way is to set your modem's tone generation interval, if it has a
command for that.  Most AT-command-set modems use S11 for this; the value is
in milliseconds.  For example on USR modems:

  ATS11=200

selects an interval of 200 milliseconds to separate each dialing tone.

2.2. Modems

2.2.1. New Modem Types

  att-keepintouch        AT&T KeepinTouch PCMCIA V.32bis Card Modem
  att-1900-stu-iii       AT&T Secure Data STU-III Model 1900
  att-1910-stu-iii       AT&T Secure Data STU-III Model 1910
  bestdata               Best Data
  cardinal               Cardinal V.34 MVP288X series.
  compaq                 Compaq Data+Fax (e.g. in Presario)
  fujitsu                Fujitsu Fax/Modem Adapter
  generic-high-speed     Any modern error-correcting data-compressing modem
  megahertz-att-v34      Megahertz AT&T V.34
  megahertz-xjack        Megahertz X-Jack
  motorola-montana       Motorola Montana
  rolm-244pc             Siemens/Rolm 244PC (AT command set)
  rolm-600-series        Siemens/Rolm 600 Series (AT command set)
  spirit-ii              QuickComm Spirit II
  suprasonic             SupraSonic V288+

One of the new types, "generic-high-speed" needs a bit of explanation.  This
type was added to easily cover other types that are not explicitly covered,
without going through the bother of adding a complete user-defined modem type.
This one works on the assumption that all the default ("factory") settings of
the modem are (a) appropriate for Kermit, and (b) recallable with the command
AT&F.

If the command to recall your modem's profile is not AT&F, use the SET MODEM
COMMAND INIT-STRING command to specify the appropriate modem command.  The
default init-string is AT&F\13 (that is, AT, ampersand, F, and then carriage
return); a survey of about 20 modern modem types chosen at random shows they
all support this -- but they might mean different things by it.  For example,
the USR Sportster or Courier needs AT&F1 (not AT&F, which is equivalent to
AT&F0, which recalls the wrong profile), so for USR modems:

  set modem type generic-high-speed
  set modem command init AT&F1\13

Of course, USR modems already have their own built-in modem type.  But if you
use this one instead, it will dial faster because it has fewer commands to
give to the modem; in that sense "&F1" is like a macro that bundles numerous
commands into a single one.  See your modem manual for details about factory
profiles and commands to recall them.

Also see Section 2.1.7 for additional hints about making dialing go faster.

2.2.2. New Modem Controls

SET MODEM CAPABILITIES <list>
  In C-Kermit 6.1, this command automatically turns MODEM SPEED-MATCHING OFF
  if SB (Speed Buffering) is in the <list>, and turns it ON if SB is absent.

SET MODEM COMMAND PREDIAL-INIT [ <text> ]
  Commands to be sent to the modem just prior to dialing.  Normally none.

SET MODEM SPEAKER { ON, OFF }
  Determines whether modem speaker is on or off while call is being placed.
  ON by default.  Note: This command does not provide fine-grained control
  over when the speaker is on or off.  Normally, ON means while the call is
  being placed, until the point at which carrier is successfully established.
  If your modem has a different speaker option that you want to choose, then
  use the SET MODEM COMMAND SPEAKER ON <text> command to specify this option.

SET MODEM COMMAND SPEAKER { ON, OFF } [ <text> ]
  Specify or override the commands to turn your modem's speaker on and off.

SET MODEM VOLUME { LOW, MEDIUM, HIGH }
  When MODEM SPEAKER is on, select volume.  Note: In some modems, especially
  internal ones, these commands have no effect; this is a limitation of the
  particular modem, not of Kermit.

SET MODEM COMMAND VOLUME { LOW, MEDIUM, HIGH } [ <text> ]
  Specify or override the commands to set your modem's speaker volume.

SET MODEM COMMAND IGNORE-DIALTONE [ <text> ]
  The command to enable blind dialing (section 2.1.4).

2.3. TELNET and RLOGIN

Note that the SET TCP commands described on pages 122-123 might be absent;
some platforms that support TCP/IP do not support these particular controls.

New commands:

SET TCP ADDRESS [ <ip-address> ]
  Specifies the IP address of the computer that C-Kermit is running on.
  Normally this is not necessary.  The exception would be if your 
  machine has multiple network adapters (physical or virtual) with a 
  different address for each adapter AND you want C-Kermit to use a 
  specific address when making outgoing connections or accepting
  incoming connections.  

SET TCP REVERSE-DNS-LOOKUP { ON, OFF, AUTO }
  Tells Kermit whether to perform a reverse DNS lookup on TCP/IP connections.
  This allows Kermit to determine the actual hostname of the host it is
  connected to, which is useful for connections to host pools, and is required
  for Kerberos connections to host pools and for incoming connections.  If the
  other host does not have a DNS entry, the reverse lookup could take a long
  time (minutes) to fail, but the connection will still be made.  Turn this
  option OFF for speedier connections if you do not need to know exactly which
  host you are connected to and you are not using Kerberos.  AUTO, the
  default, means the lookup is done on hostnames, but not on numeric IP
  addresses.

The RLOGIN section on page 123 does not make it clear that you can use the
SET TELNET TERMINAL-TYPE command to govern the terminal type that is reported
by C-Kermit to the RLOGIN server.

2.3.0. Bug Fixes   

If "set host nonexistent-host" was given (and it properly failed), followed by
certain commands like SEND, the original line and modem type were not restored
and C-Kermit thought that it still had a network hostname; fixed in 6.1.

2.3.1. Telnet Binary Mode Bug Adjustments

SET TELNET BUG BINARY-ME-MEANS-U-TOO { ON, OFF } was added to edit 192
after the book was printed.  Also SET TELNET BUG BINARY-U-MEANS-ME-TOO.
The default for both is OFF.  ON should be used when communicating with a
Telnet partner (client or server) that mistakenly believes that telling
C-Kermit to enter Telnet binary mode also means that it, too, is in binary
mode, contrary to the Telnet specification, which says that binary mode must
be negotiated in each direction separately.

2.3.2. VMS UCX Telnet Port Bug Adjustment

A new command, SET TCP UCX-PORT-BUG, was added for VMS versions with UCX (DEC
TCP/IP), applying only to early versions of UCX, like 2.2 or earlier.  If you
try to use VMS C-Kermit to make a Telnet connection using a port name (like
"telnet", which is used by default), the underlying UCX getservbyname()
function might return the service number with its bytes swapped and the
connection will fail.  If "telnet hostname 23" works, then your version of UCX
has this bug and you can put "set tcp ucx-port-bug on" in your CKERMIT.INI
file to get around it.

2.3.3. Telnet New Environment Option

The TELNET NEW-ENVIRONMENT option (RFC1572) is supported as 6.1.  This option
allows the C-Kermit Telnet client to send certain well-known variables to the
Telnet server, including USER, PRINTER, DISPLAY, and several others.  This
feature is enabled by default in Windows and OS/2, disabled by default
elsewhere.  The command to enable and disable it is:

  SET TELNET ENVIRONMENT { ON, OFF }

When ON, and you Telnet to another computer, you might (or might not) notice
that the "login:" or "Username:" prompt does not appear -- that's because your
username was sent ahead, in which case the remote system might prompt you only
for your password (similar to Rlogin).  Use "set telnet environment off" to
defeat this feature, particularly in scripts where the dialog must be
predictable.  You can also use this command to specify or override specific
well-known environment variable values:

 SET TELNET ENVIRONMENT { ACCT,DISPLAY,JOB,PRINTER,SYSTEMTYPE,USER } [ <text> ]

2.3.4. Telnet Location Option

The TELNET LOCATION option (RFC779) is supported in 6.1.  This option allows
the C-Kermit Telnet client to send a location string to the server if the
server indicates its willingness to accept one.  If an environment variable
named LOCATION exists at the time C-Kermit starts, its value is used as the
location string.  If you want to change it, use:

  SET TELNET LOCATION <text>

If you omit the <text> from this command, the Telnet location feature is
disabled.

SET TELNET ENVIRONMENT DISPLAY is used to set the DISPLAY variable that is
sent to the host, as well as the the XDISPLAY location.

2.3.5. Connecting to Raw TCP Sockets

The SET HOST and TELNET commands now accept an optional switch, /RAW-SOCKET,
at the end, only if you first give a host and a port.  Example:

  set host xyzcorp.com 23 /raw-socket
  set host 128.49.39.2:2000 /raw-socket
  telnet xyzcorp.com 3000 /raw

Without this switch, C-Kermit behaves as a Telnet client when (a) the port is
23, or (b) the port is not 513 and the server sent what appeared to be Telnet
negotiations -- that is, messages starting with 0xFF (IAC).  With this switch,
Kermit should treat all incoming bytes as raw data, and will not engage in any
Telnet negotiations or NVT CRLF manipulations.  This allows transparent
operation through (e.g.) raw TCP ports on Cisco terminal servers, through the
'modemd' modem server, etc.

2.3.6. Incoming TCP Connections

Accomplished via SET HOST * <port>, were introduced in C-Kermit 6.0, but for
UNIX only.  In Version 6.1, they are also available for VMS.

2.4. The EIGHTBIT Command

EIGHTBIT is simply a shorthand for: SET PARITY NONE, SET TERMINAL BYTESIZE 8,
SET COMMAND BYTESIZE 8; that is, a way to set up an 8-bit clean connection
in a single command.

2.5. The Services Directory

Chapter 7 of "Using C-Kermit" does not mention the ULOGIN macro, which is
used by our sample services directory, CKERMIT.KND.  Unlike UNIXLOGIN,
VMSLOGIN, etc, this one is for use with systems that require a user ID but
no password.  Therefore it doesn't prompt for a password or wait for a
password prompt from the remote service.

In version 6.1, the CALL macro was changed to not execute a SET MODEM TYPE
command if the given modem type was the same as the current one; otherwise the
new SET MODEM TYPE command would overwrite any customizations that the user
had made to the modem settings.  Ditto for SET LINE / SET PORT and SET SPEED.

2.6. Closing Connections

Until version 6.1, there was never an obvious and general way to close a
connection.  If a serial connection was open, it could be closed by "set
line" or "set port" (giving no device name); if a network connection was
open, it could be closed by "set host" (no host name).

In version 6.1, a new command closes the connection in an obvious and
straightforward way, no matter what the connection type:

  CLOSE [ CONNECTION ]

The CLOSE command was already present, and required an operand such as
DEBUG-LOG, WRITE-FILE, etc, and so could never be given by itself.  The new
CONNECTION operand is now the default operand for CLOSE, so CLOSE by itself
closes the connection, if one is open, just as you would expect, especially
if you are a Telnet or Ftp user.

2.7. Pipe Connections: Using C-Kermit with External Communication Programs

C-Kermit 6.1 includes a new ability to create and conduct sessions through
another communications program or command.  This feature, called "pipe
connections", is the opposite of the REDIRECT or external protocol feature, in
which C-Kermit makes the connection, and redirects an external command or
program over this connection.  In a pipe connection, an external program makes
the connection and C-Kermit uses it.

Pipe connections are available in UNIX, Windows 95/98/NT, and OS/2.  They
allows you to use Kermit's features (such as file transfer, scripting, and/or
international character-set conversions) on connections that Kermit might not
be able to make itself.  The commands are:

  SET NETWORK TYPE COMMAND
  SET HOST <command>

where <command> is any command that:

 (a) makes an interactive connection to another computer, and:
 (b) accesses your terminal (keyboard and screen) via standard i/o ("stdio").

(In fact, (a) is not required; see section 2.8 for details.)

The above sequence sets the network type to COMMAND for all subsequent SET
HOST commands until another SET NETWORK TYPE command is given to change it.

You can also use the new /COMMAND switch on the SET HOST command itself:

  SET HOST /COMMAND <command>

This is the same, except it doesn't change the global network type setting.

Include any command-line options that might be needed, as in this example
where C-Kermit uses another copy of itself as the communications program:

  SET HOST /COMMAND kermit -YQJ xyzcorp.com

As usual, if you include the /CONNECT switch, SET HOST enters CONNECT mode
immediately upon successful execution of the given command.  Therefore a new
command is available as a shorthand for SET HOST /CONNECT /COMMAND:

  PIPE [ <command> ]

Thus, the PIPE command works just like the TELNET and RLOGIN commands: it
makes the connection (in this case, using the given command, if any), and then
enters CONNECT mode automatically.  If the PIPE command is given without a
<command>, it continues the current connection if one is active; otherwise it
gives an error message.

The PIPE command is named after the mechanism by which C-Kermit communicates
with the <command>: UNIX pipes.  C-Kermit's i/o is "piped" through the given
command.  Here is a typical example:

  PIPE rlogin xyzcorp.com

This is equivalent to:

  SET HOST /COMMAND rlogin xyzcorp.com
  CONNECT

and to:

  SET HOST /COMMAND /CONNECT rlogin xyzcorp.com

IMPORTANT:
  If you are writing a script, do not use the PIPE, TELNET, or RLOGIN
  command unless you really want C-Kermit to enter CONNECT mode at that
  point.  Normally SET HOST is used in scripts to allow the login and
  other dialogs to be controlled by the script itself, rather than by
  an actively participating person.

Throughput of pipe connections is limited by the performance of the chosen
command or program and by the interprocess communication (IPC) method used.
In UNIX (as noted) we use pipes, which are the only IPC mechanism portable to
all varieties of UNIX; throughput here is also limited by the buffering
capacity of the pipes, which in turn depends on the underlying UNIX
implementation.

In one trial (on SunOS 4.1.3), we observed file transfer rates over an rlogin
connection proceeding at 200Kcps for downloads, but only 10Kcps for uploads on
the same connection with the same settings (similar disparities were noted in
HP-UX).  Examination of the logs revealed that a write to the pipe could take
as long as 5 seconds, whereas reads were practically instantaneous.  On the
other hand, using Telnet as the external program rather than rlogin, downloads
and uploads were a bit better matched at 128Kcps and 85Kcps, respectively.

Most external connection programs, like C-Kermit itself, have escape
characters or sequences.  Normally these begin with (or consist entirely of) a
control character.  You must be sure that this control character is not
"unprefixed" when uploading files, otherwise the external program will "escape
back" to its prompt, or close the connection, or take some other unwanted
action.  When in CONNECT mode, observe the program's normal interaction rules.
Of course C-Kermit's own escape character (normally Ctrl-\) is active too,
unless you have taken some action to disable it.

The safest course is to tell C-Kermit to SET PREFIXING ALL.  Of course you are
welcome to try unprefixing as many control characters as you like, to improve
throughput of binary file transfers.  Suppose the program's escape character
is Ctrl-] (ASCII 29); then use:

  SET PREFIXING MINIMAL     ; (or whatever)
  SET CONTROL PREFIX 29 157

Note that the character value 29 as well as that value plus 128 should both
be prefixed, since most communication programs ignore the 8th bit when looking
for the escape character.

Note that when starting a pipe connection, the connection program (such as
telnet or rlogin) might print some greeting or information messages before
starting the connection; these are quite likely to be printed with a stairstep
effect (linefeed without carriage return).  This is because the program has
become disconnected from the UNIX terminal driver; there's not much Kermit can
do about it.  Once the connection is made, everything should go back to normal.

On a similar note, some connection programs (like Solaris 2.5 rlogin) might
print lots of error messages like "ioctl TIOCGETP: invalid argument" when
used through a pipe.  They are annoying but usually harmless.  If you want to
avoid these messages, and your shell allows redirection of stderr, you can
redirect stderr in your pipe command, as in this example where the user's
shell is bash:

  PIPE rlogin xyzcorp.com 2> /dev/null

2.7.1. C-Kermit over Telnet

Although C-Kermit includes its own Telnet implementation, you might need to
use an external Telnet program to make certain connections; perhaps because it
has access or security features not available in C-Kermit itself.  The only
the caveat is that you must take care to prefix Telnet's escape character
(usually Ctrl-] = 29) when transferring files over this kind of connection:

  SET CONTROL PREFIX 29 157

and then:

  SET HOST /COMMAND /CONNECT telnet abccorp.com

or, equivalently:

  PIPE telnet abccorp.com

2.7.2. C-Kermit over Rlogin

C-Kermit includes its own Rlogin client, but this can normally be used only
if you are root, since the rlogin TCP port is privileged.  Now you can make
rlogin connections with C-Kermit through your computer's external rlogin
program, which is normally installed as a privileged program:

Note that the normal escape sequence for rlogin is Carriage Return followed by
Tilde (~).  When making Kermit connections through rlogin, we recommended that
you change the rlogin escape character to a control character, such as Ctrl-B,
and then make sure C-Kermit prefixes that control character (and its 8-bit
twin) during file transfer.  You might also need to include the "-8" switch to
enable transmission of 8-bit data.  Here is an example:

  SET CONTROL PREFIX 2 130
  PIPE rlogin "-e\2" -8 abccorp.com

2.7.3. C-Kermit over Serial Communication Programs

SET NETWORK TYPE COMMAND also lets you use programs that make serial
connections, such as cu or tip.  For example, C-Kermit can be used through cu
to make connections that otherwise might not be allowed, e.g. because C-Kermit
is not installed with the required permissions.

Suppose your uucp Devices file contains an entry for a serial device tty04
to be used for direct connections, but this device is protected against Kermit.
In this case you can:

    PIPE cu -l tty04

(Similarly for dialout devices, except then you also need to include the phone
number in the "cu" command.)

As with other communication programs, watch out for cu's escape sequence,
which is the same as the rlogin program's: Carriage Return followed by Tilde
(followed by another character to specify an action, like "." for closing the
connection and exiting from cu).  Since "~" embedded within a line is treated
as a normal data character, it is normally sufficient to ensure that carriage
return (13) and its 8-bit twin (141) are prefixed during file transfer:

  SET CONTROL PREFIX 13 141

2.7.4. C-Kermit over Secure Network Clients

  DISCLAIMER: There are laws in the USA and other countries regarding
  use, import, and/or export of encryption and/or decryption or other
  forms of security software, algorithms, technology, or intellectual
  property.  The Kermit Project attempts to follow all known statutes,
  and neither intends nor suggests that Kermit software can or should
  be used in any way, in any location, that circumvents any regulations,
  laws, treaties, covenants, or other legitimate canons or instruments 
  of law, international relations, trade, or ethics.

For secure connections or connections through firewalls, C-Kermit 6.1 can be
a Kerberos and/or SOCKS client when built with the appropriate options and
libraries.  But other application-level security acronyms and methods -- SSH,
SSL, SRP, TLS -- pop up at an alarming rate and are (a) impossible to keep up
with, (b) usually mutually incompatible, and (c) have restrictions on export
or redistribution and so cannot be included in C-Kermit itself.

However, if you have a secure Telnet (or other) client that employs one of
these security methods and that uses stdio, you can use C-Kermit through it
just as you would over cu or rlogin (previous sections).

Eventually, with IPV6, security should become an intrinsic part of the
Internet, and the bewildering assortment of mutually incompatible security
methods will be a thing of the past and software developers and users can get
on with their lives.  In the meantime, consult the following sections on the
various secure access methods.

2.7.4.1. SSH

C-Kermit presently does not work with SSH since SSH does not use stdio.

2.7.4.2. SSL

Secure Sockets Layer (SSL) is another TCP/IP security overlay, this one
designed by and for Netscape.  An SSL Telnet client is available for UNIX 
from the University of Queensland.  More info at:

  http://www.psy.uq.oz.au/~ftp/Crypto/

Interoperability with C-Kermit is unknown.

2.7.4.3. SRP

SRP(TM) is Stanford University's Secure Remote Password protocol.  An SRP
Telnet client is available from Stanford:

  http://srp.stanford.edu/srp/

Stanford's SRP Telnet client for UNIX has been tested on SunOS and works fine
with C-Kermit, as described in Section 2.7.1, e.g.

  PIPE srp-telnet xenon.stanford.edu

C-Kermit itself can be built as an SRP Telnet client on systems that have
libsrp.a installed.

2.7.4.4. SOCKS

C-Kermit can be built as a SOCKS-aware client on systems that have a SOCKS
library.  See section 8.1.1 of the ckccfg.doc file.

C-Kermit 6.1 can also be run over SOCKSified Telnet or rlogin clients with SET
NETWORK TYPE COMMAND.  Suppose the Telnet program on your system is SOCKS
enabled but C-Kermit is not.  Make Kermit connections like this:

  PIPE telnet zzz.com

2.7.4.5. Kerberos and SRP

UNIX C-Kermit can be built with MIT Kerberos V and/or Stanford University SRP
authentication and encryption.  Instructions are available in a separate
document, security.txt.  Additional modules are required that can not be
exported from the USA to any country except Canada, by US law.

2.7.4.6. FTP

SET HOST /COMMAND could, in theory, be used in conjunction with an ftp client.
For example, "pipe ftp" should allow you to script an ftp session (see section
2.8).  But this doesn't work if the ftp program does not use standard i/o for
its prompts and command (which, evidently, most UNIX ftp clients do not).

"pipe {ftp hostname}" should let Kermit converse directly with the remote ftp
server, and indeed it does; for example:

  set input timeout quit
  set host /command {ftp localhost}
  output USER myuserid\13
  input 313
  output PASS mypassword\13
  ... 

But this works only on the control connection; ftp uses a separate connection
for file transfer, and since Kermit is sending the data transfer commands
(like RETR), and not the ftp client, the ftp client does not know to start
a data connection, and so the server reports "Connection refused".

2.8. Scripting Local Programs

Any program that uses standard input and output can be invoked by the PIPE
command, even if it is not a communication program.  Example:

  C-Kermit> pipe grep Monday days.txt

Perhaps more usefully, an interactive program can be started this way.  Since,
in UNIX, there are not very many such commands, let's use Kermit itself as an
example:

  C-Kermit> pipe kermit -z

(the -z switch tells Kermit to act as if it is in the foreground even though
it will detect that its standard input is not from a terminal).  In this
situation you will notice some strange formatting, etc, but that's because
the second Kermit program does not think it is being used interactively.

Why is this useful?  Because if you start the program with SET HOST /COMMAND
rather than PIPE, you can script your interactions with it.  Here's an example
in which we start an external Kermit program, wait for its prompt, give it
a VERSION command, and then extract the numeric version number from its
response:

  set host /command {kermit -Yz}
  if fail stop 1 CAN'T OPEN COMMAND
  input 10 Kermit>
  if fail stop 1 NO KERMIT> PROMPT
  output version\13
  input 10 {Numeric: }
  if fail stop 1 NO NUMERIC
  clear input
  input 10 \10
  echo VERSION = "\fsubstr(\v(input),1,6)"
  output exit\13

This technique could be used to control any other interactive program if it
uses standard i/o, including certain shells, interactive text-mode editors
like ex, and so on.

2.9. X.25 Networking

X.25 networking is documented in "Using C-Kermit", 2nd Edition.  When the book
was published, X.25 was available only in SunOS, Solaris, and Stratus VOS.
Unlike TCP/IP, X.25 APIs are not standardized; each vendor's X.25 libraries
and services (if they have them at all) are unique.

This section describes new additions.

2.9.1. IBM AIXLink/X.25 Network Provider Interface for AIX

Support for X.25 was added via IBM's Network Provider Interface (NPI),
AIXLink/X.25 1.1, to the AIX 4.x version of C-Kermit 6.1.  Unfortunately,
AIXLink/X.25 is a rather bare-bones facility, lacking in particular any form
of PAD support (X.3, X.28, X.29).  Thus, the AIX version of C-Kermit, when
built to include X.25 networking, has neither a PAD command, nor a SET PAD
command.  The same is true for the underlying AIX system: no PAD support.
Thus it is not possible to have an interactive shell session over an X.25
connection into an AIX system (as far as we know), even from X.25-capable
Kermit versions (such as Solaris or VOS) that do include PAD support.

Thus the X.25 capabilities in AIX C-Kermit are limited to peer-to-peer
connections, e.g. from a C-Kermit client to a C-Kermit server.  Unlike the
Solaris, SunOS, and VOS versions, the AIX version can accept incoming X.25
connections:

  set network type x.25
  if fail stop 1 Sorry - no X.25 support
  ; Put any desired DISABLE or ENABLE or SET commands here.
  set host /server *
  if fail stop 1 X.25 "set host *" failed

And then access it from the client as follows:

  set network type x.25
  if fail stop 1 Sorry - no X.25 support
  set host xxxxxxx ; Specify the X.25/X.121 address
  if fail stop 1 Can't open connection
  
And at this point the client can use the full range of client commands:
SEND, GET, REMOTE xxx, FINISH, BYE.

The AIX version also adds two new variables:

  \v(x25local_nua)   The local X.25 address.
  \v(x25remote_nua)  The X.25 address of the host on the other end
                     of the connection.

C-Kermit's AIX X.25 client has not been tested against anything other than
a C-Kermit X.25 server on AIX.  It is not known if it will interoperate with
C-Kermit servers on Solaris, SunOS, or VOS.

To make an X.25 connection from AIX C-Kermit, you must:

  set x25 call-user-data xxxx

where xxxx can be any even-length string of hexadecimal digits, e.g. 123ABC.

2.9.2. HP-UX X.25

Although C-Kermit presently does not include built-in support for HP-UX X.25,
it can still be used to make X.25 connections as follows: start Kermit and
then telnet to localhost.  After logging back in, start padem as you would
normally do to connect over X.25.  Padem acts as a pipe between Kermit and
X.25.

In C-Kermit 6.1, you might also be able to avoid the "telnet localhost" step
by using:

  C-Kermit> pipe padem <address>

or:

  C-Kermit> set host /command padem <address>

This will work if padem uses standard i/o (see Section 2.7).


(3) TERMINAL CONNECTION

3.1. CONNECT Command Switches

The following switches (see section 1.5) were added to the CONNECT command
in 6.1:

  /QUIETLY
    Don't print the "Connecting to..." or "Back at..." messages.
    CQ is an invisible command synonym for CONNECT /QUIETLY.

  /TRIGGER:string
    Specify a trigger or triggers (Section 3.2) effective for this CONNECT
    command only, temporarily overriding any current SET TERMINAL TRIGGER
    values.

Note: Other switches might also be available; type "connect ?" for a list,
"help connect" for a description of each.

3.2. Triggers

Triggers were added for UNIX, VMS, AOS/VS, and K95 in C-Kermit 6.1.

SET TERMINAL TRIGGER string
  Tells C-Kermit to look for the given string during all subsequent CONNECT
  sessions, and if seen, to return to command mode automatically, as if you
  had escaped back manually.  If the string includes any spaces, you must
  enclose it in braces.  Example:

    SET TERMINAL TRIGGER {NO CARRIER}

If a string is to include a literal brace character, precede it with a
backslash:

    ; My modem always makes this noise when the connection is lost:
    SET TERMINAL TRIGGER |||ppp\{\{\{\{UUUUUUU

If you want Kermit to look for more than one string simultaneously, use the
following syntax:

    SET TERMINAL TRIGGER {{string1}{string2}...{stringn}}

In this case, C-Kermit will return to command mode automatically if any of 
the given strings is encountered.  Up to 8 strings may be specified.

If the most recent return to command mode was caused by a trigger, the new
variable, \v(trigger), shows the trigger value; otherwise \v(trigger) is
empty.

The SHOW TRIGGER command displays the SET TERMINAL TRIGGER values as well as
the \v(trigger) value.

(4) FILE TRANSFER

4.0. BUG FIXES AND MINOR CHANGES

C-Kermit 6.0 could send packets "out of window" if the window size was
greater than 1 and ACKs had arrived out of order.  Fixed in 6.1.

ADD SEND-LIST followed by MOVE did not delete original files; fixed in 6.1.

Carrier loss was not detected during transfer; in 6.1 C-Kermit checks for
this (but results can not be guaranteed).  In any case, the protocol will
eventually time out if the connection is lost.

In 5A(190) through 6.0.192, the GET and RECEIVE as-name did not properly
override the RECEIVE PATHNAMES setting.  In 6.1 it does.

Version 6.1 adds a /BRIEF switch to the STATISTICS command, to display a short
file-transfer statistics report.  /BRIEF is now the default.  Use /VERBOSE to
see the full display, which is about 25 lines long.

The preinstalled definition of the FAST macro did not take enough factors into
account.  Now it sets packet lengths and window sizes appropriate to the
configuration.  Furthermore, in IRIX only, it restricts the SEND packet length
to 4000, to work around a bug in the IRIX Telnet server (see ckuker.bwr, IRIX
section).  To see the built-in definition of the FAST macro, type "show macro
fast".  To change it, simply define it to be whatever you want -- it's just
a macro, like any other.

Many non-Columbia Kermit protocol implementations fail to follow the protocol
definition or to implement it correctly.  A common source of error is in the
protocol negotiation strings exchanged at the beginning of a transfer.  The
bad Kermits are confused by them, even though the protocol says to ignore
any items that are not understood.  As a last resort, you can tell Kermit to
omit newer negotiations from the end of this string with the following command:

  SET { SEND, RECEIVE } NEGOTIATION-STRING-MAX-LENGTH <number>

Detailed explanation of its use is beyond the scope of this document; contact
the Kermit Project if you think you need to use it.

4.1. FILE-TRANSFER FILENAME TEMPLATES

Prior to C-Kermit 6.1 and Kermit 95 1.1.12 the only options that could be
used to affect the names of files being transferred were SET FILENAMES
{ LITERAL, CONVERTED } and SET { SEND, RECEIVE } PATHNAMES { ON, OFF }, plus
the "as-name" feature of the SEND (MOVE, etc) and RECEIVE commands.

Previously, the as-name could be used only for a single file.  For example:

  SEND FOO BAR

would send the file FOO under the name BAR, but:

  SEND *.TXT anything

was not allowed, since it would give the same name to each file that was sent.
When receiving:

  RECEIVE FOO

would rename the first incoming file to FOO before storing it on the disk,
but subsequent files would not be renamed to FOO, since this would result in
overwriting the same file repeatedly.  Instead, they were stored under the
names they arrived with.

Beginning in C-Kermit 6.1 and Kermit 95 1.1.12, it is possible to
specify as-names in SEND, RECEIVE, and related commands even for file
groups.  This is accomplished by using replacement variables in the as-name,
along with optional material such character-string functions and/or constant
strings.  An as-name containing replacement variables is called a filename
template.

The key to filename templates is the new variable:

  \v(filename)

which is usable only during file transfer (its value is unpredictable and
undependable in command mode).  During file transfer it is replaced by the
name of each file currently being transferred.  So, for example:

  send *.txt \v(filename).new

sends each file with its own name, but with ".new" appended to it.  Of course
if the name already contains periods, this could confuse the file receiver, so
you can also achieve fancier effects with constructions like:

  send *.txt \freplace(\v(filename),.,_).new

which replaces all periods in the original filename by underscores, and then
appends ".new" to the result.  So, for example, oofa.txt would be sent as
oofa_txt.new.

Another new variable that is useful in this regard is \v(filenumber), which
is the ordinal number of the current file in the file group, so you can also:

  send *.txt FILE\flpad(\v(filenum),2,0)

resulting in a series of files called FILE00, FILE01, FILE02, etc.  (At the
end of the transfer, \v(filenum) tells the number of files that were
transferred).

If you specify a constant as-name when sending a file group:

  send *.txt thisnameonly

Kermit complains and asks you to include replacement variables in the as-name.
You should generally use \v(filename) or \v(filenumber) for this purpose,
since other variables (with the possible exception of \v(time), \v(ntime),
(and less likely) \v(date), and \v(ndate)) will not change from one file to
the next.  But Kermit will accept any as-name at all that contains any kind of
variables for file group, even if the variable will not change.  So:

  send *.txt \%a

is accepted, but all files are sent with the same name (the value of \%a, if
it has one).  If the variable has no value at all, the files are sent under
their own names.

Of course, the value of \%a in the previous example need not be constant:

  define \%a FILE\flpad(\v(filenum),2,0)_at_\v(time)
  send *.txt \%a

The RECEIVE command, when given without an as-name, behaves as always, storing
all incoming files under the names they arrive with, subject to SET FILE NAME
and SET RECEIVE PATHNAMES modifications.

However, when an as-name is given in the RECEIVE command, it is applied to
all incoming files rather than to just the first.  If it does not contain
replacement variables, then the current FILE COLLISION setting governs the
result.  For example:

  receive foo

will result in incoming files named foo, foo.~1~, foo.~2~, and so on, with the
default FILE COLLISION setting of BACKUP.  If it does contain replacement
variables, of course they are used.

When receiving files, the \v(filename) variable refers to the name that was
received in the incoming file-header packet, BEFORE any processing by SET
FILE NAMES or SET RECEIVE PATHNAMES.  Since the filenames in file-header
packets are usually in uppercase, you would need to convert them explicitly
if you want them in lowercase, e.g.:

  receive \flower(\v(filename)).new

On the command-line, use templates as shown above as the -a option argument,
bearing in mind the propensity of UNIX and perhaps other shells to treat
backslash as a shell escape character.  So in UNIX (for example):

  kermit -s oofa.* -a x.\\v(filenum)

By the way, this represents a change from 6.0 and earlier releases in
which the as-name (-a argument or otherwise) was not evaluated by the command
parser.  Thus, for example, in VMS (where the shell does not care about
backslashes), it was possible to:

  kermit -s oofa.txt -a c:\tmp\oofa.txt

Now backslashes in the as-name must be quoted not only for the shell (if
necessary) but also for Kermit itself:

  kermit -s oofa.txt -a c:\\tmp\\oofa.txt      ; Kermit only
  kermit -s oofa.txt -a c:\\\\tmp\\\\oofa.txt  ; Shell and Kermit

You can also use the \fliteral() function for this:

  kermit -s oofa.txt -a \fliteral(c:\tmp\oofa.txt)      ; Kermit only
  kermit -s oofa.txt -a \\fliteral(c:\\tmp\\oofa.txt)   ; Shell and Kermit

4.2. FILE-TRANSFER PIPES AND FILTERS

4.2.1. INTRODUCTION

Beginning in C-Kermit 6.1 and Kermit 95 1.1.12, it is possible to send from a
command, or "pipe", as well as from a file, and to receive to a pipe or
command.  In a typical example, we might want to transfer an entire directory
tree from one UNIX system to another (but without using the methods described
in Sections 4.3, 4.10, 4.11, and 4.15).  We could do this in multiple steps as
follows:

  1. Create a tar archive of the desired directory tree
  2. Compress the tar archive
  3. Transfer it in binary mode to the other computer
  4. Decompress it
  5. Extract the directory tree from the tar archive

But this is inconvenient and it requires a temporary file, which might be
larger than we have room for.

The new pipe-transfer feature lets you do such things in a single step,
and without intermediate files.

Additional new features, also discussed here, let you specify pre- and post-
processing filters for outbound and incoming files, and give you a way to
insert the output from shell or system commands into C-Kermit commands.

The file-transfer related features are available only with Kermit protocol,
not with any external protocols, nor with K95's built-in XYZMODEM protocols
(because XYZMODEM recovers from transmission errors by rewinding the source
file, and you can't rewind a pipe).

This section begins by discussing the simple and straightforward use of these
features in UNIX, in which pipes and input/output redirection are a
fundamental component and therefore "just work", and then goes on to discuss
their operation in Windows and OS/2, where matters are much more complicated.

4.2.1.1. TERMINOLOGY

Standard Input
  This is a precise technical term denoting the normal source of input for
  a command or program, which is the keyboard of your terminal by default,
  but which can be redirected to a file or pipe.

Stdin
  Abbreviation for Standard Input.
  
Standard Output
  A precise technical term denoting the normal destination for output from a
  command or program, which is your terminal screen by default, but which can
  be redirected to a file.

Stdout
  Abbreviation for Standard Output.
  
Stdio  
  Abbreviation for Standard Input / Standard Output.

I/O
  Abbreviation for Input / Output.

Shell
  Text-based system command processer, such as the UNIX shell, DOS
  COMMAND.COM, etc. 

Pipe
  A mechanism by which the standard output of one program is sent to
  the standard input of another.

Pipeline
  A series of programs connected by pipes.

4.2.1.2. NOTATION  

In command descriptions, "<command>" is replaced by a shell or system command
or pipeline.  The command names specified in these commands are interpreted by
your shell, just as if you were typing them at the shell prompt, and so if
they are in your PATH, they will be found in the expected manner.  Therefore
you don't have to specify complete pathnames for commands that are programs
(but it shouldn't hurt if you do).

The normal notation for I/O redirection is as follows:

  <  Read Stdin from the given file.
  >  Send Stdout to the given file.
  |  Send Stdout from the command on the left to the command on the right.

Examples:

sort < foo > bar
  Sorts the lines in file "foo" and writes the results to file "bar" 

grep -c "some text" *.txt | grep -v ":0" | sort | pr -3 | lpr
  This is a command pipeline composed of 5 commands:

  grep -c "some text" *.txt
    Looks in all files whose names end with ".txt" for the string "some text"
    and writes to Stdout the names of each file followed by a colon and the
    number of occurrences in each.

  grep -v ":0"
    Prints to Stdout the lines from Stdin that do NOT contain the string ":0",
    in this case, it removes the names of files that do not contain "some
    text".

  sort
    Sorts the lines from Stdin alphabetically to Stdout.

  pr -3
    Arranges the lines from Stdin in three columns.

  lpr
    Prints its Stdin on the default printer.

Note that the Kermit features described here work only with commands that use
Stdio.  If you attempt to use them with commands whose input and output can
not be redirected, Kermit will most likely get stuck.  Kermit has no way of
telling how an external command works, nor what the syntax of the shell is, so
it's up to you to make sure you use these features only with redirectable
commands.

The quoting rules of your shell apply to the <command>.  Thus in UNIX, where
C-Kermit tries to use your preferred shell for running commands, shell
"metacharacters" within commands must be escaped if they are to be taken
literally, using the methods normal for your shell.  For example, the UNIX tr
(translate) command must have its arguments in quotes:

  tr "[a-z]" "[A-Z]"

otherwise the shell is likely to replace them by all filenames that match,
which is probably not what you want.  This is also true when using your shell
directly, and has nothing to do with Kermit.

4.2.1.3. SECURITY

Some sites might not wish to allow access to system commands or external
programs from within Kermit.  Such access, including all the features
described here, can be disabled in various ways:

 1. When building from source code, include -DNOPUSH among the CFLAGS.
 2. At runtime, give the NOPUSH command.
 3. For server mode, give the DISABLE HOST command.
 4. Implicit use of pipes can be disabled as described in section 4.2.4.

Note: 3 and 4 are not necessary if you have done 1 or 2.

4.2.2. Commands for Transferring from and to Pipes

SEND /COMMAND sends data from a command or command pipeline, and RECEIVE
/COMMENT writes data to a command or pipeline.  The GET /COMMAND command
asks a server to send material, and then writes the incoming material to a
command or pipeline.  These features, along with switches (like "/COMMAND",
described in section 4.7) are new to C-Kermit 6.1.  The following
synonymous are also provided:

  CSEND    = SEND /COMMAND
  CRECEIVE = RECEIVE /COMMAND
  CGET     = GET /COMMAND

None of these commands can be used if a SEND or RECEIVE FILTER (respectively,
Section 4.2.3) is in effect, or if a NOPUSH command (Section 4.2.1.3) has been
given, or if the current protocol is not Kermit.

4.2.2.1. Sending from a Command

SEND /COMMAND <command> [ <as-name> ]
SEND /AS-NAME:<as-name> /COMMAND <command>
CSEND <command> [ <as-name> ]
  These three forms are the same.  They work like the SEND command, but
  instead of sending a file, it sends the standard output of the given
  <command>, either under the command's own name, or else with the given
  <as-name>.  If the <command> contains spaces, it must be enclosed in braces.
  Braces should also be used for the <as-name> if it contains spaces.  If
  braces are included around either the <command> or the <as-name>, they are
  removed after parsing but before use.  As with SEND, the transfer is in text
  or binary mode according the current FILE TYPE setting, unless you override
  the global transfer mode by including a /TEXT or /BINARY switch.  The
  <command> must require no input.

When sending from a command or pipeline, C-Kermit has no way of knowing
in advance how much data will be sent, and so it can not send the size
to the other Kermit in the Attribute packet, and so the receiving Kermit
has no way of displaying "percent done" or a progress bar (thermometer).

Examples that make sense in text mode (illustrated by common UNIX commands):

  SEND /COMMAND finger
  CSEND finger
    sends the current "finger" listing (who's logged in) under the
    name "finger".  The two forms "send /command" and "csend" are
    equivalent; we won't bother showing them both in the rest of the
    examples.

  SEND /COMMAND:{finger}
  CSEND {finger}
    Same as previous example (braces are removed from "{finger}").

  SEND /COMMAND:{ finger }
  CSEND { finger }
    Same as previous example, but note that the spaces are kept.  This
    does not prevent the shell from running the "finger" program, but
    its output is sent under the name " finger " (with a leading and
    trailing space).

  SEND /COMMAND:finger /AS-NAME:userlist
  CSEND finger userlist
    sends the current finger listing under the name "userlist".

  SEND /COMMAND:{finger | sort -r} /AS-NAME:userlist
  CSEND {finger | sort -r} userlist
    sends the current finger listing, sorted in reverse order, under the
    name "userlist".  The braces are needed to distinguish the <command>
    from the <as-name>.

  SEND /COMMAND:{finger | sort -r} /AS-NAME:{userlist}
  CSEND {finger | sort -r} {userlist}
    Same as previous example (braces are removed from "{userlist}").

  SEND /COMMAND:{finger | sort -r} /AS-NAME:{\freplace(\v(filename),\32,_)}
  CSEND {finger | sort -r} {\freplace(\v(filename),\32,_)}
    Like the previous example, but sends the output of the <command> under
    the name of the command, but with all spaces (\32) replaced by underscores,
    so the as-name is "finger_|_sort_-r".

  Examples that make sense in binary mode (three equivalent forms are shown):

  SEND /COMMAND /BINARY {tar cf - . | gzip -c} mydir.tar.gz
  SEND /COMMAND /BINARY /AS-NAME:mydir.tar.gz {tar cf - . | gzip -c}
  CSEND /BINARY {tar cf - . | gzip -c} mydir.tar.gz
    Makes a tar archive of the current directory, compresses it with the GNU
    gzip program, and sends it as "mydir.tar.gz".  The other Kermit can, of
    course, just store it as a file, or it can use CRECEIVE to uncompress and
    dearchive it as part of the transfer process.

When using a "pipeline" of commands in the <command> field, obviously,
the first command must not require any input, and the last command should
produce some output, and all intermediate commands should get some input and
produce some output.

4.2.2.2. Receiving to a Command

RECEIVE /COMMAND <command>
CRECEIVE <command>
  This is like RECEIVE, except incoming material is written to the standard
  input of the given command, in text or binary mode according to the normal
  rules for file reception.  Be sure to include a redirector to a file (if the
  command normally writes to standard output), or the output of the command
  won't go anywhere.  The <command> may contain spaces; braces are not needed,
  but they are removed if used.

WARNING: C-Kermit has no way of knowing anything about the <command>, or even
whether it is a command.  Thus this command will always cause C-Kermit to
enter protocol mode, as long as some text is specified in the <command> field.
However, if the text does not correspond to a command, the transfer will
eventually fail with a message such as "Error writing data" or "Failure to
close file".

Examples for text mode (in UNIX):

  RECEIVE /COMMAND sort -r > reverse.txt
  CRECEIVE sort -r > reverse.txt
    The text that is received is sorted in reverse order and stored in
    the file "reverse.txt".  The two forms shown are equivalent.

  RECEIVE /COMMAND {sort -r > reverse.txt}
  CRECEIVE {sort -r > reverse.txt}
    The same as the previous example; if braces are included, they are
    simply removed.

  RECEIVE /COMMAND {sort -r > \flower(\v(filename)).reverse}
  CRECEIVE {sort -r > \flower(\v(filename)).reverse}
    Same but stores result under the incoming filename, lowercased, and
    with ".reverse" appended to it.

  RECEIVE /COMMAND sort
  CRECEIVE sort
    Does nothing useful, since the output of sort has nowhere to go.

  RECEIVE /COMMAND sort -r | pr -3 | lpr -Plaserjet
  CRECEIVE sort -r | pr -3 | lpr -Plaserjet
    The text that is received is sorted in reverse order, arranged into
    three columns, and sent to the "laserjet" printer.

  Examples for binary mode:

  RECEIVE /COMMAND:{gunzip -c | tar xf -}
  CRECEIVE {gunzip -c | tar xf -}
    Assuming the data that is received is a compressed tar archive,
    uncompresses the archive and passes it to tar for extraction.  In this
    case the braces are needed because otherwise the final "-" would be
    taken as a command continuation character (see "Using C-Kermit", 2nd
    Edition, p.33).

GET /COMMAND <remote-file> <command>
GET /COMMAND /AS-NAME:<command> <remote-file>
CGET <remote-file> <command>
  This command tells the Kermit client to send a GET request for the given
  remote file to a Kermit server.  Unlike GET, however, the incoming material
  is written to a command, rather than to a file.  If the <remote-file> or the
  <command> contain spaces, they must be enclosed in braces.  The same
  cautions about the <command> apply as for CRECEIVE.  Examples (for UNIX):

  GET /COMMAND oofa.txt sort -r > oofa.new
  GET /COMMAND {oofa.txt} {sort -r > oofa.new}  
  CGET oofa.txt sort -r > oofa.new
  CGET {oofa.txt} {sort -r > oofa.new}
    These four are equivalent.  Each of them requests the server to send
    its "oofa.txt" file, and as it arrives, it is sorted in reverse order
    and written to "oofa.new".
  
  GET /COMMAND {profile exec a} lpr
  GET /COMMAND {profile exec a} {lpr}
  GET /COMMAND /AS-NAME:lpr {profile exec a}
  GET /COMMAND /AS-NAME:{lpr} {profile exec a}
  GET /COMMAND /AS:lpr {profile exec a}
  CGET {profile exec a} lpr
  CGET {profile exec a} {lpr}
    Here the remote filename contains spaces so it MUST be enclosed in
    braces.  As it arrives it is sent to the lpr program for printing.
    Braces are optional around "lpr" since it contains no spaces.

  GET /COMMAND *.txt {cat >> new.txt}
  GET /AS-NAME:{cat >> new.txt} /COMMAND *.txt 
  CGET *.txt {cat >> new.txt}
    This gets all the ".txt" files from the server and concatenates them 
    all into a single "new.txt" file on the client.

  GET /COMMAND *.txt {echo \v(filename)>>new.txt;cat>>new.txt}
  CGET *.txt {echo \v(filename)>>new.txt;cat>>new.txt}
    As above, but inserts each file's name before its contents.

4.2.3. Using File-Transfer Filters

The commands described in section 4.2.2 let you send the output of a command,
or receive data into a command.  But what if you want to specify preprocessing
for files that you send, or postprocessing of files that you receive, even
when multiple files are involved?  For this you need a way to specify send and
receive filters.  The commands are SET SEND FILTER and SET RECEIVE FILTER;
SHOW PROTOCOL displays the current settings.

4.2.3.1. The SEND Filter

SET SEND FILTER [ <command> ]
  This command specifies a <command> to be run on any file that you SEND (or
  MOVE, MSEND, etc).  It also applies to files sent when in server mode, in
  response to GET commands, but not to the results of REMOTE commands like
  REMOTE DIRECTORY, REMOTE TYPE, REMOTE HOST, etc.  The <command> may be, but
  need not be, enclosed in braces; if it is, the braces are stripped before
  use.  The output of this command is sent, rather than the file itself.  The
  current FILE TYPE setting (TEXT or BINARY) applies to the output of the
  command.  The <command> must contain at least one instance of \v(filename),
  for which the name of the actual file is substituted.  If the <command> is
  omitted, the send filter is removed and files are sent in the normal manner.

The SET SEND FILTER sets up a "global" filter -- that is, one that applies to
all subsequent file-sending commands until you change or remove it.  You can
also specify a "local" filter to be used in a specific file-sending command by
using the /FILTER switch (see section 1.5); for example:

  SEND /FILTER:<command> [ <other-switches> ] <filename>

Besides \v(filename), you can include any other script programming notation in
the send filter: variable names, array references, calls to built-in string or
other functions, and so on.  These are evaluated during file transfer, NOT
during parsing, and they are evaluated separately for each file.

When the SEND or MOVE (SEND /DELETE) command is used with a send filter, the
output from the filter is sent under the file's original name unless you
specify an "as-name" or template.  The Attribute packet (if any) contains the
original file's attributes (size, creation date, etc).  So (for example) if
the filter changes the file's size, the progress thermometer might be wrong.
(We can't send the size of the output from the filter, because it is not known
until the transfer is finished.)  If you prefer that the size not be sent, use
"set attributes size off".

You can not use send filters with RESEND (SEND /RECOVER) or PSEND
(SEND /START).

Examples for text mode:

  SET SEND FILTER sort -r \v(filename)     ; Braces may be omitted
  SET SEND FILTER {sort -r \v(filename)}   ; Braces may be included
  SEND *.txt    
    This sends every file in the current directory whose name ends with
    ".txt" under its own name, but with its lines sorted in reverse order.

  SEND /FILTER:{sort -r \v(filename)} *.txt
    Same as above, but the filter applies only to this SEND command.
    Braces are required in this case.

  SET SEND FILTER {sort -r \v(filename)}
  SEND oofa.txt reverse.txt
    Sends the oofa.txt file with its lines sorted in reverse order under
    the name "reverse.txt".

  SET SEND FILTER {sort -r \v(filename)}
  SEND oofa.* \v(filename).reverse
    Sends all the oofa.* files with their lines sorted in reverse order;
    each file is sent under its own name but with ".reverse" appended to it.

  SET SEND FILTER {tr "[a-z]" "[A-Z]" < \v(filename)}
  SEND *.txt
    Sends all ".txt" files under their own names, but uppercasing their
    contents.

Note that the SEND FILTER applies not only to files that are sent with
SEND, MOVE, MSEND, etc, but also to files sent by the C-Kermit server in
response to GET requests.

Examples for binary mode:

  SET SEND FILTER {gzip -c \v(filename)}
  SEND /BINARY oofa.doc oofa.doc.gz
    Sends the oofa.doc file, compressed by gzip, as oofa.doc.gz.

  SEND /BINARY /FILTER:{gzip -c \v(filename)} oofa.doc oofa.doc.gz
    As above, but the filter applies only to this SEND command.

  SET SEND FILTER {gzip -c \v(filename)}
  SEND /BINARY oofa.* \fupper(\replace(\v(filename),.,_)).GZ
    Sends all the oofa.* files, compressed by gzip, each under its own name,
    but with the name uppercased, all periods within the name converted to
    underscores, and ".GZ" appended to it.  So, for example, "oofa.txt"
    is sent as "OOFA_TXT.GZ".

In the gzip examples, note that the amount of data that is sent is normally
less than the original file size because gzip compresses the file.  But Kermit
sends the original file size ahead in the attribute packet anyway (unless you
tell it not too).  Thus the transfer will probably appear to terminate early,
e.g. when the receiver's file-transfer display thermometer is only at 40%.
If this annoys you, tell Kermit to "set attribute length off".  On the other
hand, you can use the final position of the thermometer as a measure of the
effectiveness of compression.

4.2.3.2. The RECEIVE Filter

SET RECEIVE FILTER [ <command> ]
  This command specifies that the given <command> will be run on any file
  that is received before it is written to disk.  The <command> may be, but
  need not be, enclosed in braces; if it is the braces are stripped before
  use.  The following two commands are equivalent:

    SET RECEIVE FILTER sort -r > \v(filename)
    SET RECEIVE FILTER {sort -r > \v(filename)}

  The RECEIVE filter <command> may contain a "\v(filename)" sequence to be
  replaced by the incoming filename from the file header packet, but it is not
  required.  However you must use it whenever your filter would normally write
  to Stdout, otherwise its output will be lost.

  The RECEIVE filter <command> may contain one or more "\v(filename)"
  sequence to be replaced by the incoming filename from the file header
  packet, but it is not required.  However you must use it whenever your
  filter would normally write to Stdout, otherwise its output will be lost.

RECEIVE /FILTER:<command> and GET /FILTER:<command> can also be used to
specify a filter to be used for only one file-transfer operation.

UNIX examples for text mode:

  SET RECEIVE FILTER lpr
  RECEIVE
    All the files that are received are sent to the default UNIX print
    spooler.

  RECEIVE /FILTER:lpr
    Same as above, except the lpr filter is used only with this
    RECEIVE command.

  RECEIVE lpr
    This is probably not what you want; it creates a file called lpr.

  SET RECEIVE FILTER {sort -r > \v(filename)}
  RECEIVE
    Stores each incoming file with its lines sorted in reverse order, 
    under its own name.

  RECEIVE /FILTER:{sort -r > \v(filename)}
    As above, but the filter is used only for this RECEIVE command.

  SET RECEIVE FILTER sort -r > \v(filename)
  RECEIVE reverse.txt
    Stores each incoming file with its lines sorted in reverse order,
    under the name "reverse.txt".  The actual result depends on the
    FILE COLLISION setting.  If it is OVERWRITE and multiple files arrive,
    then each incoming file destroys the previous one.  If it is BACKUP
    (the default), filename conflicts are resolve by adding "version numbers"
    to the filenames: reverse.txt, reverse.txt.~1~, reverse.txt.~2~, etc.

  SET RECEIVE FILTER sort -r > \v(filename)
  RECEIVE \v(filename).reverse
    Stores each incoming file with its lines sorted in reverse order, 
    under the name it arrived with, but with ".reverse" appended to it.

  SET RECEIVE FILTER sort -r > \v(filename)
  RECEIVE \flower(\v(filename)).reverse
    Like the previous example, but ensures that the filename is lowercase.

Examples for binary mode:  
  
  SET RECEIVE FILTER gunzip -c > \v(filename)
  RECEIVE
    This receives one or more presumably compressed file and uncompresses
    each one into a file having the same name it was sent with.  For example,
    if the file is sent with the name OOFA.TXT.GZ, it is stored with that
    name, even after decompression.
  
  SET RECEIVE FILTER gunzip -c > \v(filename)
  RECEIVE \flower(\fsubstring(\v(filename),1,\flength(\v(filename))-3))
    Like the previous example, but the resulting filename has its rightmost
    three characters removed from it and the remainder is lowercased.  So if
    the incoming filename is OOFA.TXT.GZ, it is stored as oofa.txt after
    decompression.

Of course you don't want to type such long hideous commands, so we have also
introduced several new functions:

\fstripx(string[,character])
   This function removes the rightmost segment of the string that starts with
   the given character.  If no character is given, period (.) is used.  Thus
   it is most conveniently used for stripping the extension from a filename
   (or the decimal portion from a floating-point number written in US/UK
   style).  Examples:

     \fstripx(OOFA.TXT.GZ)             => OOFA.TXT
     \fstripx(OOFA.TXT.GZ,.)           => OOFA.TXT
     \fstripx(OOFA.TXT.GZ,X)           => OOFA.T
     \fstripx(\fstripx(OOFA.TXT.GZ))   => OOFA
     \fstripx($100.00)                 => $100

\fstripn(string,number)
   Removes the rightmost <number> characters from the string.  Examples:

     \fstripn(OOFA.TXT.GZ)             => OOFA.TXT.GZ
     \fstripn(OOFA.TXT.GZ,3)           => OOFA.TXT
     \fstripn(OOFA.TXT.GZ,7)           => OOFA

\flop(string[,char])
   Removes the leftmost segment of the string that ends with the given
   character.  If no character is given, period (.) is used.  Examples:

     \flop(OOFA.TXT.GZ)               => TXT.GZ
     \flop(OOFA.TXT.GZ,.)             => TXT.GZ
     \flop(OOFA.TXT.GZ,X)             => T.GZ

To remove the leftmost <number> characters, just use \fsubstring(s,<number>+1).
To return the rightmost <number> characters, use \fright(s,<number>).

So the hideous example:

  receive \flower(\fsubstring(\v(filename),1,\flength(\v(filename))-3))

can now be written as:

  receive \flower(\fstripx(\v(filename)))

That is, the filename stripped of its extension and then lowercased.  This
is not only shorter and less hideous, but also does not depend on the
length of the extension being 3.

Note that when a receive filter is in effect, this overrides your FILE
COLLISION setting, since Kermit has no way of knowing what the final
destination filename will be (because it does not know, and can not be
expected to know, the syntax of every version of every command shell on
every platform on the planet).

4.2.4. Implicit Use of Pipes

If you wish, C-Kermit can also examine incoming filenames to see if they
start with "!", and if so, the subsequent text is treated as a command to
read from or write to.  For example, if a Kermit client sends the following
command to a Kermit server that has this feature:

  get !finger | sort

or (equivalently):

  get {!finger | sort}

the server will run the "finger" program, pipe its standard output to the
"sort" program, and send sort's standard output back to you.  Similarly, if
you:

  send oofa.txt !sort -r > oofa.new

or, equivalently:

  send oofa.txt {!sort -r > oofa.new}

or:

  send /as-name:{!sort -r > oofa.new} oofa.txt 

this has the receiver send the contents of the incoming oofa.txt file to
the sort program, which sorts the text in reverse order and stores the
result in oofa.new.

This use of the exclamation mark should be familiar to UNIX users as the
"bang" feature that lets you run an external application or command from
within another application.

Kermit's "bang" feature is disabled by default, since it is not unheard for
filenames to actually begin with "!".  So if you want to use this feature,
you must enable it with the following command:

SET TRANSFER PIPES { ON, OFF }
  ON enables the recognition of "!" notation in incoming filenames during
  file transfer as an indicator that the remaining text is the name of a
  command.  OFF, the default, disables this feature and uses the text as
  a filename in the normal fashion.  This command does NOT affect SEND
  /COMMAND, GET /COMMAND, CSEND, etc.

So using a combination of CSEND (SEND /COMMAND) and the "bang" feature, you
can transfer a directory tree all in one command (assuming the remote
Kermit supports pipe transfers and has them enabled):

  CSEND {tar cf - . | gzip -c} {!gunzip -c | tar xf -}

or:

  SEND /COMMAND:{tar cf - . | gzip -c} /as:{!gunzip -c | tar xf -}

Pay close attention to the syntax.  Braces are needed around the <command>
because it contains spaces; braces are needed around the <as-name> because
it ends with "-".  The <as-name> must begin with "!" or receiving Kermit will
not recognize it as a command.  The CSEND command must NOT begin with "!" 
unless you are running a command whose name really does start that character.

Similarly, you have a Kermit server send a directory tree to be unpacked
on the client end:

  CGET {!tar cf - . | gzip -c} {gunzip -c | tar xf -}

or:

  GET /COMMAND {!tar cf - . | gzip -c} /as:{gunzip -c | tar xf -}

Notice how, in this case, the bang is required in the remote command, to
distinguish it from a filename, but not in the local command, since by
definition of CGET (or GET /COMMAND), it is known to be a command.

SEND and RECEIVE FILTERs supersede the bang feature.  For example, if a
file arrives under the name "!gunzip -c | tar xf -", but the receiving Kermit
also has been given a command like:

  set receive filter sort -r > \v(filename)

then the incoming data will be sorted rather than gunzipped. 

Finally, if SET TRANSFER PIPES is ON (and in this case, this must be done in
your C-Kermit initialization file), you can send from a pipe on the C-Kermit
command line:

  kermit -s "!finger | sort -r" -a userlist

In this case the "filename" contains spaces and so must be quoting using
your shell's quoting rules.

4.2.5. Success and Failure of Piped Commands

Commands or programs started by Kermit as a result of CSEND or CRECEIVE
commands, CGET, SEND /COMMAND, REDIRECT commands (see section 4.2.9.2),
implicit use of pipes, RUN commands, and so forth, should return their exit
status codes to the Kermit command that caused them to be run, and
therefore IF SUCCESS and IF FAILURE tests after these commands should work
as expected.  For example:

  CSEND blah < filename

should fail if there is no command called "blah" or if there is no file called
"filename".  However, this is not foolproof and sometimes C-Kermit might think
a command succeeded when it failed, or vice versa.  This is most likely to
happen when the highly system-dependent methods that Kermit must use to
determine a command's exit status code do not supply the right information.

It can also happen because some commands might define success and failure
differently from what you expect, or because you are using a pipeline composed
of many commands, and one of them fails to pass failing exit status codes up
the chain.  The most likely culprit is the shell itself, which in most cases
must be interposed between Kermit and any external program to be run.

In any case, you can examine the following variable to find out the exit
status code returned to Kermit by the process most recently run by any command
that runs external commands or programs, including CSEND, CRECEIVE, REDIRECT,
RUN, etc:

  \v(pexitstat)

In UNIX, Windows and OS/2, the value should be -2 if no command has been run
yet, 0 if the most recent command succeeded, -1, -3, or -4 if there was an
internal error, and a positive number returned by the command itself if the
command failed.  If the number is in the range 1-127, this is the program's
exit status code.  If it is 128 or greater, this is supposed to indicate that
the command or program was interrupted or terminated from outside itself.

In VMS, it is the actual exit status code of the command that was run.  This
is an odd number if the command succeeded, and an even number if it failed.
You can see the associated message as follows:

  run write sys$output f$message(\v(pexitstat))

Or, more conveniently, use the new Kermit function:

  echo \ferrstring(\v(pexitstat))

which converts a system error code (number) to the corresponding message.

4.2.6. Cautions about Using Pipes to Transfer Directory Trees 

Although utilities such as tar and zip/unzip might be available on different
platforms (such as UNIX and Windows), this does not necessarily mean you can 
use them successfully to transfer directory trees between unlike platforms.
For example:

  CSEND {tar cf - . | gzip -c} {!gunzip -c | tar xf -}

when used from UNIX to Windows will have satisfactory results for binary
files, but not for text files.  UNIX text files have lines ending with
Linefeed (LF) only, whereas Windows text files have lines ending in Carriage
Return and Linefeed (CRLF).  Thus any text files that were in the archive
formed by the first tar command will be unpacked by the second tar command
in their original form, and will display and print incorrectly in Windows
(except in applications that have been explicitly coded to handle UNIX-format
text files).  On the other hand if you told gzip to use "text mode" to do
record format conversion (assuming there was a way to tell it, as there is
with most "zip" programs), this would destroy any binary files in the archive.

Furthermore, if the archive contains text files that are written in languages
other than English, the "special" (accented and/or non-Roman) characters are
NOT translated, and are therefore likely show up as gibberish on the target
system.  For example, West European languages are usually encoded in ISO Latin
Alphabet 1 in UNIX, but in PC code page 850 on the PC.  Capital A with acute
accent is code point 193 (decimal) Latin-1, but 181 in CP850.  So A-acute in
the UNIX file becomes Middle Box Bottom on the PC, and similarly for all the
other special characters, and for all other languages -- Greek, Russian,
Hebrew, Japanese, etc.

So when transferring text files between unlike platforms, you should use
direct Kermit file transfers so Kermit can apply the needed record-format and
character-set transformations.  Use pipelines containing archivers like tar or
zip only if all the files are binary or the two systems use the same record
format and character set for text files.

Also see sections 4.3, 4.10, 4.11, and 4.15 for how to transfer directory
trees between both like and unlike systems directly with Kermit.

4.2.7. Pipes and Encryption

Of course pipelines could be used for encrypted file transfers, assuming
proper precautions could be taken concerning the transmission of the key.
But there is rarely a good way to do this.  To illustrate using UNIX crypt:

  csend {crypt key < filename} {!crypt key > filename}

Or, more ambitiously:   

  csend {tar cf - . | gzip -c | crypt key} {!crypt key | gunzip -c | tar xf -}

transmits the key in the file header packet as part of the (clear-text) remote
command, defeating the entire purpose of encrypting the file data.

But if you are connected in terminal mode to the remote computer and type:

  creceive {crypt key > filename}

at the remote Kermit prompt, you have also transmitted the key in clear text
over the communications link.

At present, the only secure way to use CSEND and CRECEIVE with an encryption
filter is to have a human operator at both ends, so the key does not have to
be transmitted.

Theoretically it would be possible to use PGP software (Pretty Good Privacy,
by Phil Zimmerman, Phil's Pretty Good Software) to avoid key transmission
(since PGP uses separate public and private key and "lets you communicate
securely with people you've never met, with no secure channels needed for
prior exchange of keys"), but the specific method has yet to be worked out.

  HINT: See the PGP User's Guide, e.g. at:
  http://www.telstra.com.au/docs/PGP/
  Especially the topic "Using PGP as a UNIX-Style Filter":
  http://www.telstra.com.au/docs/PGP/pgpdoc2/pgpdoc2_17.html

In any case, better and more convenient security options are now available:
Kerberos authentication and encryption (described in the kerberos.txt file)
and the new ability to run C-Kermit "though" other communication programs,
described in Section 2.7.

4.2.8. Commands and Functions Related to Pipes

4.2.8.1. The OPEN !READ and OPEN !WRITE Commands

These are fully described in "Using C-Kermit", and are generally useful with
reading output from commands that produce many lines, or writing many lines
into commands that accept them.

4.2.8.2. The REDIRECT Command

A second method of I/O redirection is offered by the REDIRECT command.
This is a rather advanced and tricky feature that is presently supported
only in UNIX C-Kermit, in OS-9 C-Kermit, and in Kermit 95.  Syntax:

REDIRECT <command>
  Runs the given <command>, sending its standard output to the current
  communications channel (SET LINE, SET PORT, or SET HOST connection),
  and reading its standard input from the same connection.  Works only in
  local mode -- i.e. a connection is required -- and then only if the given
  command uses Standard I/O.

Example:

  redirect finger

runs the local "finger" command and sends its output over the connection as
plain text, where presumably there is a process set up to read it.  Another
example:

  redirect finger | sort -r

shows the use of a pipeline.

Note: REDIRECT differs from CSEND/CRECEIVE in two important ways: (1) it does
not use the Kermit protocol, and (2) it uses a bidirectional pipe rather than
a one-way pipe.

The primary use of the REDIRECT command is to run external protocols, such as
sz/rz in UNIX for ZMODEM, when they work over Standard I/O (Note: only
pre-1988 versions of the publicly-distributed sz/rz programs use Standard I/O;
newer redirectable ZMODEM programs must be licensed from Omen Technology).
Example:

  set host xyzcorp.com
  (login, etc)
  redirect sz oofa.zip

lets you make a Telnet connection with C-Kermit and then do a ZMODEM transfer
over it.  ZMODEM protocol messages go both ways over the same connection
simultaneously.

One user reports successfully using C-Kermit on Linux as his PPP dialer;
after the connection is made, and PPP started on the far end, he tells C-Kermit
to "redirect pppd".

In theory, you can also redirect an interactive process.  For example, suppose
you tell Kermit 95 to wait for an incoming TCP/IP connection:

  set host * 3000

and then tell C-Kermit on UNIX to:

  set host kermit95hostname 3000
  redirect ksh

and then tell Kermit 95 to CONNECT: now you are talking to the UNIX K-shell;
you can give commands (pwd, ls, etc) and see the results.  In practice, the
K-shell's terminal modes are messed up because it is "smart" and knows it is
being redirected, and so acts in a decidedly inhospitable manner (other
applications like EMACS, vi, etc, simply refuse to run if their standard i/o
has been redirected).

4.2.8.3. Receiving Mail and Print Jobs

As of 6.1, and in UNIX only, files that are sent to C-Kermit as mail (when
the other Kermit uses a MAIL or SEND /MAIL command) or to be printed (via
REMOTE PRINT or SEND /PRINT) are now piped directly to the mail or print
program, rather than written to temporary files and then mailed or printed and
then deleted.  This has the advantages of (a) not requiring a temporary file,
and (b) allowing mail to have a proper subject in place of the filename.
Temporary files were bad not only because they required (a) space, and (b)
writeability of the current directory, but also because using them could
result in wiping out an existing file.  See section 4.7 for more about SEND
/MAIL and SEND /PRINT.

4.2.8.4. Pipe-Related Functions

The \fcommand(<command>) function runs the given shell or system command and
returns the command's standard output as its value (with any newline
characters stripped from the end), unless the result is too long, in which
case it returns the empty string.  The maximum length for the result is at
least 1022 bytes, and it might be longer on some platforms.  Examples (UNIX):

  C-Kermit> echo "\fcommand(date)"
  "Fri Apr 18 13:31:42 1997"
  C-Kermit> echo "\fcommand(finger | wc -l)" ; how many users logged in?
  "      83"
  C-Kermit> evaluate \fcommand(finger | wc -l) * 2
  166
  C-Kermit> echo Welcome to \fcommand(tty) on \fcommand(date)
  Welcome to /dev/ttyre on Fri Apr 18 13:31:42 1997
  C-Kermit> echo "\fcommand(ls oofa.*)"
  "oofa.c
  oofa.h
  oofa.o"
  C-Kermit> cd /directory-with-thousands-of-files
  C-Kermit> echo "\fcommand(ls -l)" ; This would be too long
  ""
  C-Kermit>

If a command's output would be too long, you can use the other, more laborious
method of reading from a command: OPEN !READ <command>, READ each line,
CLOSE !READ.

The \frawcommand(<command>) function is identical to \fcommand(<command>),
except it does not remove trailing newline characters:

  C-Kermit> echo "\frawcommand(date)"
  "Fri Apr 18 13:31:42 1997
  "
  C-Kermit> echo "\frawcommand(ls oofa.*)"
  "oofa.c
  oofa.h
  oofa.o
  "
  C-Kermit>

Use \frawcommand() if you want to retain the final line terminators, or if
the command's output is "binary".  But remember that if the result of this
(or any other) function contains any NUL (ASCII code 0) characters, the first
NUL will terminate the result string because this is how C strings work
(it's "C-Kermit", remember?).

These functions are useful not only locally, but also in the client/server
arena.  If you need to get the results from a system command on the server
end into a variable on the client end, just do:

  remote query kermit command(date)

The result is in the local \v(query) variable; see "Using C-Kermit", 2nd Ed.,
pp.359-360 for details.

4.3. Automatic Per-File Text/Binary Mode Switching

When transferring files between like systems (e.g. UNIX-to-UNIX), binary mode
can be used for all files (unless character-set translation is needed), and in
fact Kermit programs of recent vintage recognize each others' platforms and
switch to binary mode automatically when it is appropriate (e.g. DOS to OS/2,
or UNIX to UNIX).

When transferring files between unlike systems, however, (e.g. UNIX-to-DOS),
some files (such as executable program images) must be transferred in binary
mode but others (such as plain-text files) must be transferred in text mode so
their record format can be appropriately converted.  If a binary file is
transferred in text mode, it is ruined.  If a text file is transferred in
binary mode, then at the very least, its format can be incorrect; at worst it
is also corrupted because its character set was not converted.

4.3.1. Exceptions

VMS C-Kermit, when sending files, switches to text or binary mode
automatically for each file, based on the characteristics of the file that are
recorded in the directory entry (in this case, the record format); thus the
mechanisms described in this section do not apply to VMS C-Kermit.  See the
VMS Appendix in "Using C-Kermit" for details.

Kermit versions that support LABELED or IMAGE transfer mode are likewise
not affected by this feature when one of those modes is selected.

Kermit versions that support file-transfer pipes and filters are not affected
by this feature when pipes or filters are used, since the output of a pipe or
filter (such as gzip) is likely to require transfer in a different mode than
the original file.

4.3.2. Overview

Stream-oriented file systems such as in UNIX and DOS do not record any
information about the file to tell us whether the file should be transferred
in binary or text mode, and so until version 6.1, C-Kermit sent all files from
UNIX, AOS/VS, Windows, OS/2, etc, in the same mode: whatever the user said in
the most recent SET FILE TYPE command, or else whatever mode was chosen
automatically according to the rules on page 236 of "Using C-Kermit", 2nd Ed.

C-Kermit 6.1 lets you provide lists of patterns that are used to separately
determine the file type for each individual file being transfered.  A pattern
is a string, possibly containing the special characters "*" (which matches any
string of zero of more characters) and/or "?" (which matches any single
character).  For example "a*b" matches all files whose names start with "a"
and end with "b", such as "ab", "arb", "ababababab", etc, but not "ababa".
And "a?b" matches any file whose name starts with "a", ends with "b", and is
exactly 3 characters long.

  NOTE: You can include ? in command files and macro definitions, but in
  order to type it in a command, you must prefix it with \ to override its
  normal function of giving help.

When you have specified filename recognition patterns, C-Kermit can transfer
the ones whose names match any of the binary-mode patterns in binary mode, and
those with names that match any of the text-mode patterns in text mode, and
those whose names match neither in the prevailing mode you have chosen.

4.3.3. Commands

SET FILE PATTERNS { ON, OFF }
  This tells Kermit whether to do per-file filename pattern-matching to
  determine text or binary mode.  The normal setting is ON.  Use OFF to
  disable this feature (without resetting your pattern lists).  Also note
  that if you have selected LABELED file transfer (SET FILE TYPE LABELED),
  or if you are RESENDing (= SEND /RECOVER), these take precedence over
  filename-matching patterns and all files are sent in labeled mode.

SET TRANSFER MODE MANUAL
  Disables the use of filename patterns, no matter what the FILE PATTERNS
  setting.

REMOTE SET TRANSFER MODE MANUAL
  Client command to disable automatic transfer mode, and therefore also
  filename patterns, in the server.  Synonym: REMOTE SET XFER MODE MANUAL.

SET FILE BINARY-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
  A list of zero or more patterns, separated by spaces (not commas).  Letters
  in a pattern are case-sensitive if the underlying filenames are case
  sensitive (as in UNIX), and case-insensitive otherwise (as in Windows).  If
  a file's name is matched by any pattern in the list and SET FILE PATTERNS is
  ON, the file is sent in binary mode.  Examples:

    SET FILE BINARY-PATTERNS *.gz *.Z *.tar *.zip *.o *.so *.a *.out ; UNIX
    SET FILE BINARY-PATTERNS *.EXE *.ZIP *.OBJ *.COM ; DOS or OS/2 or Windows

  If a pattern must contain spaces, enclose it in braces.

SET FILE TEXT-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
  Like SET FILE BINARY-PATTERNS, but the patterns choose text files rather
  than binary ones.  Examples:

    SET FILE TEXT-PATTERNS *.TXT *.KSC *.HTM *.HTML *.BAT ; DOS, Windows, OS/2

ADD BINARY-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
  Adds one or more patterns to the BINARY-PATTERN list.

ADD TEXT-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
  Adds one or more patterns to the TEXT-PATTERN list.

REMOVE BINARY-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
  Removes one or more patterns from the BINARY-PATTERN list.  The given
  patterns are matched with the ones in the BINARY-PATTERNS list with
  case sensitivity if the underlying file system has case-sensitive names
  (as do UNIX and OS-9), otherwise with case independence.

REMOVE TEXT-PATTERNS [ <pattern> [ <pattern> [ <pattern> ... ] ] ]
  Removes one or more patterns from the TEXT-PATTERN list.

SHOW PATTERNS
  Displays the current pattern selections.

Whenever you give a SET FILE BINARY-PATTERNS or SET FILE TEXT-PATTERNS
command, the previous list is replaced.  If you give one of these commands
without a pattern list, the previous list is removed.

When patterns are active and files are being sent, text patterns (if any) are
applied first (but only if not RESENDing and not sending in LABELED mode),
then binary patterns, so if the same pattern appears in both lists, binary
mode is chosen.

4.3.4. Examples

Here's an example that might be used when sending files from UNIX:

  set file type binary
  set file text-patterns *.c *.h *.w *.txt makefile
  set file binary-patterns *.o
  msend makefile wermit wart ck*.c ck*.h ck*.w ck*.o ck*.txt  

Note that "wermit" and "wart" do not match any patterns so they are sent in
the prevailing mode, which is binary.  Also note the use of "makefile" as a
pattern that does not contain any wildcard characters (there is no other
convention to distinguish among "wermit" and "wart", which are binary
executables, and "makefile", which is a text file, purely by their names).

Most C-Kermit implementations have a default pattern list built in, which
includes patterns that are almost certain to succeed in picking the right
transfer mode.  Others are omitted due to ambiguity.  For example ".doc",
".hlp", and ".ini" are generally binary types in Windows but text types
everywhere else.  You can see the default pattern list by starting C-Kermit
without its initialization file (e.g. "kermit -Y") and using the SHOW PATTERNS
command.  If you will be depending on this feature, be sure to examine the
list carefully in conjunction with the applications that you use.

Hint: Put your most commonly-used safe pattern declarations in your C-Kermit
customization file (ckermod.ini, .mykermrc, k95custom.ini, etc).

As noted, SET FILE PATTERNS is ON by default.  Sometimes, however, it is
desirable, or necessary, to force files to be sent in a particular mode, and
often this must be done from the command line (e.g. when using Kermit as a
download helper in a Web browser like Lynx).  The -V command-line options is
equivalent to SET FILE PATTERNS OFF and SET TRANSFER MODE MANUAL.  Example:

  kermit -Vis oofa.txt

forces oofa.txt to be sent in binary mode, even though ".txt" might match a
text pattern.

4.4. File Permissions

"Permissions" refers to a code associated with a file that specifies who is
allowed to access it, and in what manner.  For example, the owner, the
owner's group(s), and everybody else, might be allowed various combinations
of Read, Write, Append, Execute, or Listing access.

The permission code goes by different names on different platforms.  In UNIX,
it might be called the filemode.  In VMS, it is called the file protection
(or protection mask).

The comments in this section presently apply only to the UNIX and VMS versions
of C-Kermit, to which these features were added in version 6.1; the DOS,
Windows, and OS/2 file systems embody no notions of protection, and so MS-DOS
Kermit and Kermit 95 do not send file permissions, and ignore them when
received.

4.4.1. Inherited from Old Files

  This section applies to UNIX only; in VMS the default protection 
  for new files is the user's default protection as shown by the VMS 
  SHOW PROTECTION command.

If a file arrives that has the same name as an existing file, the actions
taken depend on the current FILE COLLISION setting: BACKUP, OVERWRITE, RENAME,
etc, as documented in "Using C-Kermit".  But now the new file (if it is
created at all) automatically inherits the permissions (mode bits) of the
existing file, rather than getting the default permissions for the user and
directory, if the incoming file does not come with its own permission codes.

In this case, all mode bits are inherited except the directory bit, since the
incoming file can not possibly be a directory.  (In any case, it is not
possible to receive a file that has the same name as an existing directory.)

4.4.2. Set from Incoming File

File permissions can be conveyed as part of the file transfer process, in
accordance with the Kermit protocol definition.  If the file sender puts
system-dependent and/or system-independent versions of the file protection
(permissions) into the Attribute (A) packet, the file receiver can set the new
file's permissions from them.  If the protection was not sent, then the new
file's permissions are either inherited from a previous version of the same
file, or set according the system's default for new files.

When the incoming A packet contains system-dependent permissions, the file
receiver checks to see if the sender has the same system ID (e.g. both the
sending and receiving systems are UNIX, or both are VMS); if so, it decodes
and uses the system-dependent permissions, if any; otherwise it uses the
generic ones (if any) and applies them to the owner field, setting the other
fields appropriately as described in the following sections.

Setting the incoming file's protection from the A packet is controlled by SET
ATTRIBUTES PROTECTION (or PERMISSION), which is ON by default, and its status
is displayed by SHOW ATTRIBUTES.

The main benefit of this feature is to not have to "chmod +x" an executable
file after transfer from UNIX to UNIX.  Its cross-platform benefits are less
evident.

Note: VMS-to-VMS transfers take place in LABELED mode by default, because the
two C-Kermits recognize each other's platform as VMS, and switch automatically
into this mode, in which all of a file's attributes are preserved in the
transfer.  In this case, the protection mask (and other information) is taken
from the file's internal information, and this takes precedence over any
information in the Attribute packets.  You can defeat the automatic switching
into LABELED mode (if you want to) with SET TRANSFER MODE MANUAL.

4.4.2.1. System-Specific Permissions

System-specific file permissions are used when the two Kermit programs
recognize each other as running on the same type of system.  For example,
both are running under some form of UNIX (it doesn't matter which UNIX
variation -- HP-UX, Solaris, AIX, etc -- all use the same scheme for file
permissions); or both are running under VMS (even if one is on an Alpha and
the other on a VAX, and/or one is old and the other is new).

4.4.2.1.1. UNIX

UNIX supports three categories of users, File Owner, Group, and World,
and three types of file access permission: Read, Write, and Execute.  Thus,
a UNIX file's permissions are expressed in 9 bits.

The system-dependent permission string for UNIX is a 3-digit octal string, the
low-order 9 bits of the st_mode member of the stat struct; we deliberately
chop off the "file format" bits because they are not permissions, nor do we
convey the setuid/setgid bits, lock bit, sticky bit, etc.  The new file has
the low-order 9 bits of its permissions set to those of the original file.

4.4.2.1.2. VMS

VMS supports four categories of users, System, File Owner, Group, and World,
and four types of file access permission: Read, Write, Execute, and Delete.
Thus, a VMS file's permissions are expressed in 16 bits.

The system-dependent protection string for VMS is a 4-digit hexadecimal
string, corresponding to the internal-format protection word of the file
(RWED for each of World,Group,Owner,System).  The new file gets all 16
protection bits from the original file.

4.4.2.2. System-Independent Permissions

The system-independent ("generic") protection is used when the system IDs of
the two Kermit programs do not agree (e.g. one is UNIX, the other is VMS).  In
this case the Owner field of the new file's permissions is set as indicated by
the generic protection, which encodes the following permissions (not all of
which are applicable to every file system): Read, Write, Append, Execute,
Delete, Search.

In UNIX, the Group and World permissions are set according to your umask,
except that execute permission is NOT set in these fields if it was not also
set in the owner field.

In VMS, the System, Group, and World permissions are set according to your
default file permission (as shown in VMS by SHOW PROTECTION, and set by SET
PROTECTION=(...)/DEFAULT), except that no permissions are allowed in these
fields that are not in the owner fields.

Note that the VMS and UNIX interpretations of Execute permission are not
identical.  In UNIX, a file (binary executable, shell script, etc) may not
be executed unless it has Execute permission, and normally files that are
not intended for execution do not have Execute permission.  In VMS, most files
that have Read permission also have Execute permission, and files (binary
executables, DCL command procedures) that have Read permission but not Execute
permission can still be executed.

4.5. File Management Commands

4.5.1. The DIRECTORY Command

The DIRECTORY command in UNIX was changed in 6.1 to accept a free-form
operand, which is simply passed to the system's "ls" command.  So now you can
use "directory -lt c* | more" or whatever you like.  For that matter you can
even enter "ls -lt c* | more" at the C-Kermit prompt, since "ls" is an
invisible synonym for "directory".

The DIRECTORY command in most other C-Kermit versions already behaved this
way, so in VMS (for example), you could (and still can) give commands like:

  C-Kermit> directory /size/date/protection oofa.*;0

4.5.2. The CD and BACK Commands

In 6.1, the CD command has a new friend, the BACK command.  BACK
means "CD to my previous current directory".  A second BACK brings you back
to where you were before the first one; thus successive BACK commands switch
back and forth between two directories.

4.5.2.1. Parsing Improvements

The CD command, as well as other commands that parse a directory name, were
changed in 6.1 to provide all the expected functions: completion on Tab
or Esc, directory-name lists on ?, etc.  Other affected commands include
SET SERVER GET-PATH, SET TEMP-DIRECTORY, SET FILE DOWNLOAD-DIRECTORY, and
SPACE.  CD and REMOTE CD also now work with logical names.

In VMS, the situation is a bit complicated since a directory name can look
like "DEV:", "[FOO.BAR]", "DEV:[FOO.BAR]", "[FOO]BAR.DIR;1", etc.  Completion
and ?-help might not always work, but they do in many cases.  Examples:

  cd ?           Lists all subdirectories of the current directory
  cd []?         Ditto
  cd k?          Ditto, but only those starting with K
  cd [foo]?      Lists all subdirectories of the [FOO] directory
  cd [-]?        Lists all subdirectories of the superior directory
  cd [--]?       Lists all subdirectories of the directory 2 levels up
  cd [...]?      Lists all directories below the current one
  cd [foo.?      Does not work.

C-Kermit allows all of the following in VMS:

  cd bar         CD to subdirectory BAR of the current directory
  cd .bar        Ditto
  cd [.bar]      Ditto
  cd bar.dir     etc...
  cd bar.dir;
  cd bar.dir;1
  cd [foo.bar]
  cd bar.baz     This can go more than 1 level deep...
  cd dir:        (where logical name DIR is defined as [FOO.BAR])

As well as the following:

  cd ..          Go up one level as in UNIX
  cd .           The current directory
  cd             My login directory

Note that "cd -" (go up one level) does not work as expected, because "-" is
Kermit's command continuation character.  However, "cd - ", "cd [-]", and "cd
{-}" have the desired effect (and so does "cd ..", which is easier to type).

4.5.2.2. The CDPATH

The CD command in the UNIX, Windows, OS/2, and VMS versions of C-Kermit, as of
version 6.1 / 1.1.12, searches the CDPATH for the given directory, if it is not
absolute and if a CDPATH environment variable is defined.  Example (in UNIX
ksh):

  $ export CDPATH=$HOME:$HOME/kermit:/tmp

Now if you give a "cd xxx" command, no matter what your current directory is,
if the "xxx" directory is not a subdirectory of your current directory, then
the xxx subdirectory of your home directory is used or if that does not exist, 
then the xxx subdirectory of the kermit subdirectory of your home directory is
used or if that does not exist, then /tmp/xxx is used.  This is how the ksh
"cd" command works, and now the C-Kermit CD command works the same way.

In VMS, you can define CDPATH to be a list of directories that contain actual
directory delimiters, and/or logical names representing directories, using
commas to separate them, e.g.:

  $ define cdpath [HOME],[SOMEOTHERDIR],[HOME.MISC]

or:
  $ define cdpath SYS$LOGIN:,DISK1:[HOME],DISK2:[SCRATCH.IVAN]

Example:
  $ define cdpath SYS$LOGIN:,[IVAN],[OLAF],[OLGA.MISC]
  $ kermit
  DISK1:[OLGA] C-Kermit> cd blah

tries the BLAH subdirectory of the user's login directory, then [OLGA.BLAH],
[IVAN.BLAH], [OLAF.BLAH], and [OLGA.MISC.BLAH], in that order, using the first
one it finds, failing if it finds none.

4.5.3. Creating and Removing Directories

The MKDIR command now allows you to create multiple directories at once:

  C-Kermit> mkdir a/b/c/d

creates the directory a in the current directory (if it doesn't exist
already), and then creates a subdirectory b of the a directory (if it didn't
exist already), and so on.

If you use MKDIR to try to create a directory that already exists, C-Kermit
will print a warning ("?Directory already exists"), but the MKDIR command
will still succeed.  If you want to avoid the warning message, use
IF DIRECTORY first to check if the directory already exists.

The RMDIR command, however, will not remove more than one directory, nor
will it remove a directory that contains any files.  (There is, as yet, no
RMDIR /RECURSIVE command, although one might be added later.)

In VMS, these commands (like CD) are more forgiving of your syntax than is the
DCL comamnd shell; "mkdir oofa" is equivalent to "mkdir [.oofa]" and so on.
Also in VMS, you'll find that C-Kermit's RMDIR command is easier than deleting
a directory in DCL, since it automatically first gives it owner delete
permission if you are the owner.

4.5. The DELETE Command

Now has switches, /VERBOSE and /QUIET.  If /VERBOSE is given, each file is
listed, along with the status of the deletion (OK, Failed, etc), and a summary
of files deleted and bytes freed is printed at the end.  UNIX and K95 only.

4.6. Starting the Remote Kermit Server Automatically

As noted on pages 275-276 of "Using C-Kermit" 2nd edition, you can have Kermit
send "kermit receive" commands automatically when it is in remote mode and you
give a SEND or similar command, to start the remote Kermit receiver in case it
is not already started.  The "kermit receive" commands are specified by:

  SET PROTOCOL KERMIT <binary-receive-command> <text-receive-command>

As of version 6.1, you can also specify a command to be sent to the host
in advance of any Kermit packets when you give a GET-class or REMOTE command,
to start up a Kermit server on the remote end in case one is not already
started.  So the new syntax of the SET PROTOCOL KERMIT command is:

  SET PROTOCOL KERMIT [ <s1> [ <s2> [ <s3> ] ] ]

where:

       Default      Meaning
  s1   kermit -ir   Remote "kermit receive in binary mode" command.
  s2   kermit -r    Remote "kermit receive in text mode" command.
  s3   kermit -x    Remote "start kermit server" command.

NOTE: If the remote Kermit is 6.0 or later, the following are recommended
for fast startup and high-performance file transfer:

  s1   kermit -YQir Kermit receive binary, skip init file, fast.
  s2   kermit -YQTr Kermit receive text, skip init file, fast.
  s3   kermit -YQx  Kermit server, skip init file, fast.

If the remote is C-Kermit 6.1, add I (uppercase letter I) to the command-line
options if you have made a Telnet or Rlogin connection to the host, to enable
streaming protocol (ckermit2.upd Section 4.20).

NOTE 2: "kermit -x" starts up C-Kermit in server mode and leaves it in server
mode.  So after you have given your client commands from Kermit 95 (GET,
REMOTE xxx, etc), you must send a FINISH command to make the remote Kermit
server exit.  C-Kermit 6.1 has a new -O option, which is equivalent to -x but
causes the server to exit automatically after executing the first command from
the client; in the case a good s3 string would be "kermit -YQO".

4.7. File-Transfer Command Switches

Over the years, various new methods of transferring a file have accumulated,
until we had, in addition to the SEND command, also MOVE (send and then
delete), MAIL (send as email), REMOTE PRINT (send to be printed), CSEND (send
the output of a command), PSEND (send a part of a file), BSEND (send in binary
mode), RESEND (resume an interrupted SEND), etc etc.  Similarly: GET, REGET,
CGET, RETRIEVE, and so on.

Not only is it confusing to have different names for these commands, many of
which are not real words, but this also does not allow for combinations, like
"send a file as mail, then delete it".

In C-Kermit 6.1, the SEND, GET, and RECEIVE commands were restructured to
accept modifier switches (see section 1.5).

4.7.1. SEND Switches

Without switches, the SEND command still works exactly as before:

  send oofa.txt      ; send a single file
  send oofa.*        ; send multiple files
  send oofa.txt x.x  ; send with as-name
  send               ; send from SEND-LIST

But now the following modifier switches may be included between "send" and the
filename.  Zero, one, two, or more switches may be included in any combination
that makes sense.  Switch names (such as /BINARY) can be abbreviated, just
like any other keywords.  Most of these switches work only when using Kermit
protocol (/TEXT and /BINARY are the exceptions).

  /AFTER:date-time
    Specifies that only those files modified after the given date-time
    (see section 1.6) are to be sent.  Examples:
    
      send /text /after:{2-Feb-1997 10:28:30} *.txt
      send /text /after:\fdate(oofa.txt) *.txt

  /AS-NAME:text
    Specifies "text" as the name to send the file under.
    You can also still specify the as-name as the second filename on the
    SEND command line.  The following two commands are equivalent:

      send oofa.txt oofa.new
      send /as:oofa.new oofa.txt

  /BEFORE:date-time
    Specifies that only those files modified before the given date-time
    (section 1.6) are to be sent.

  /BINARY
    Performs this transfer in binary mode without affecting the global
    transfer mode, overriding not only the FILE TYPE and TRANSFER MODE
    settings, but also the FILE PATTERN setting, but for this SEND command
    only.  In other words, SEND /BINARY means what it says: send the file
    in binary mode, regardless of any other settings.  Example:

      set file type text      ; Set global transfer mode to text
      send /binary oofa.zip   ; Send a file in binary
      send oofa.txt           ; This one is sent in text mode

  /COMMAND
    SEND /COMMAND is equivalent to CSEND (section 4.2) -- it says to send
    the output from a command, rather than the contents of a file.
    The first "filename" on the SEND command line is interpreted as the name
    of a command; the second (if any) is the as-name.  Examples:

      send /command {grep Sunday oofa.txt} sunday.txt
      send /as-name:sunday.txt /command {grep Sunday oofa.txt}
      send /bin /command {tar cf - . | gzip -c} {!gunzip -c | tar xf -}
    
  /DELETE
    Deletes the file (or each file in the group) after it has been sent
    successfully (but does not delete it if it was not sent successfully).
    SEND /DELETE is equivalent to MOVE.  Has no effect when used with
    /COMMAND.  Example:

      send /delete *.log

  /RECURSIVE
    Descend the through the directory tree when locating files to send.
    Automatically sets /PATHNAMES:RELATIVE.  Explained in section 4.11.

  /EXCEPT:pattern
    Specifies that any files whose names match the pattern, which can be a
    regular filename, or may contain "*" and/or "?" metacharacters (wildcards),
    are not to be sent.  Example:

      send /except:*.log *.*

    sends all files in the current directory except those with a filetype of
    ".log".  Another:

      send /except:*.~*~ *.*

    sends all files except the ones that look like Kermit or EMACS backup
    files (such as "oofa.txt.~17~").

    The pattern matcher is the same one used by IF MATCH <string> <pattern>,
    so you can test your patterns using IF MATCH.  If you need to match a
    literal * or ?, precede it by a backslash (\).  If the pattern contains
    any spaces, it must be enclosed in braces:

      send /except:{Foo bar} *.*

    The pattern can also be a list of up to 8 patterns.  In this case, the
    entire pattern must be enclosed in braces, and each sub-pattern must also
    be enclosed in braces; this eliminates the need for designating a
    separator character, which is likely to also be a legal filename
    character, and therefore a source of confusion.  You may include spaces
    between the subpatterns but they are not necessary.  The following two
    commands are equivalent:

      send /except:{{ck*.o} {ck*.c}} ck*.?
      send /except:{{ck*.o}{ck*.c}} ck*.?

    If a pattern is to include a literal brace character, precede it with \.

  /FILENAMES:{CONVERTED,LITERAL}
    Use this switch to override the current global SET FILE NAMES setting
    for this transfer only.

  /FILTER:<command>
    This specifies a filter to pass the file through before sending it.
    See the section on file-transfer pipes and filters.  The /FILTER switch
    applies only to the file-transfer command it is given with; it does not
    affect the global SEND FILTER setting, if any.

  /IMAGE
    VMS: Sends in image mode.  Non-VMS: same as /BINARY.

  /LABELED
    VMS and OS/2 only: Sends in labeled mode.

  /LARGER-THAN:number
    Specifies that only those files that are longer than the given number
    of bytes are to be sent.

  /LIST:filename
    Specifies that the files to be sent are listed in a file with the given
    name.  The file is one filename per line.  The syntax is not checked in
    any way; the filename is taken literally.  Thus it does not use or
    depend on any Kermit-specific syntax.  In particular, backslashes are
    not treated specially, leading and trailing spaces are not stripped,
    etc.  However, if a filename contains wildcards, they are expanded.
    Example: If a file named files.txt contains the following lines:

      blah.txt
      oofa*
      x.x

    (but without leading or trailing spaces), then the C-Kermit command
    "send /list:files.txt" will send the files blah.txt, x.x, and all
    files whose names start with "oofa", assuming the files exist and are
    readable.  The /LIST switch, can, of course, be used with other
    switches when it makes sense, for example, /EXCEPT, /BINARY, /AFTER,
    /SMALLER, /MOVE-TO, /DELETE, /AS-NAME with a template, etc.

  /MAIL:address
    Sends the file as e-mail to the given address or addresses.
    "send /mail:address filename" is equivalent to "mail filename address".
    You can include multiple addresses separated by commas.  Examples:
      send /mail:kermit-support@columbia.edu packet.log
      send /mail:cmg,fdc,jrd oofa.txt
    As with any switch argument, if the address or address list contains any
    spaces, you must enclose it in braces.  The format of the addresses must
    agree with that understood by your mail-sending program.

  /MOVE-TO:directory-name
    Specifies that after each (or the only) source file is sent successfully,
    and ONLY if it is sent successfully, it should be moved to the named
    directory.  If the directory name contains spaces, enclose it in braces.
    If the directory does not exist, it is created if possible; if it can't be
    created, the command fails and an error message is printed.  Example:
      send /text /move-to:backup *.txt

  /NOT-AFTER:date-time
    Specifies that only those files modified at or before the given date and
    time are to be sent.

  /NOT-BEFORE:date-time
    Specifies that only those files modified at or after the given date and
    time are to be sent.

  /PATHNAMES:{OFF,ABSOLUTE,RELATIVE}
    Use this switch to override the current global SET SEND PATHNAMES setting
    for this transfer only.  /PATHNAMES:ABSOLUTE or RELATIVE also sets
    /FILENAMES:LITERAL (also for this transfer only) since pathnames are not
    sent otherwise.

  /RENAME-TO:text
    Specifies that after the, or each, source file is sent successfully, and
    ONLY if it is sent successfully, it should be renamed to the name given.
    If the name contains spaces, enclose it in braces.  If a file group is
    being sent, then the "text" must contain a variable reference such as
    \v(filename) (see section 4.1).  Example:
      send /rename-to:ok_\v(filename) *.*
    This sends each file in the current directory and if it was sent
    successfully, changes its name to begin with "ok_".

  /SMALLER-THAN:number
    Specifies that only those files that are smaller than the given number
    of bytes are to be sent.

  /SUBJECT:text
    Subject for email.  Actually, this is just a synonym for /AS-NAME.  If the
    text includes spaces, you must enclose it in braces.  If you don't specify
    a subject (or as-name), the name of the file is used as the subject.
    Example:
      send /mail:kermit-support@columbia.edu /subj:{As requested} packet.log

  /PRINT:options
    Sends the file to be printed, optionally specifying options for the
    printer.  Equivalent to REMOTE PRINT filename options.  Examples:

      send /print oofa.txt              ; No options.
      send /print:/copies=3 oofa.txt    ; "/copies=3" is a VMS PRINT switch.
      send /print:-#3 oofa.txt          ; "-#3" is a UNIX lpr switch.

  /PROTOCOL:name
    Uses the given protocol to send the file (Kermit, Zmodem, etc) for this
    transfer without changing global protocol.  Only available in Kermit 95,
    UNIX, and OS-9.  Example:

      set protocol kermit               ; Set global protocol
      send /proto:zmodem /bin oofa.zip  ; Send just this file with Zmodem
      send oofa.txt                     ; This file is sent with Kermit

  /QUIET
    When sending in local mode, this suppresses the file-transfer display.

  /RECOVER
    Used to recover from a previously interrupted transfer; SEND /RECOVER
    is equivalent RESEND.  The global transfer mode must be binary, or else
    the /BINARY switch must be included.
    
  /STARTING:number
    Starts sending the file from the given byte position.
    SEND /STARTING:n filename is equivalent to PSEND filename n.

  /TEXT
    Performs this transfer in text mode without affecting the global
    transfer mode, overriding not only the FILE TYPE and TRANSFER MODE
    settings, but also the FILE PATTERN setting, for this SEND command
    only.  In other words, SEND /TEXT really send the file in text mode,
    regardless of any other settings or negotiations.

About mail...  Refer to section 4.1.  The same rules apply as for file
transfer.  If you are mailing multiple files, you can't use an as-name (in
this case, a subject) unless it contains replacement variables like
\v(filenum).  For example, if you:

  send /mail:somebody@xyz.com *.txt

Then each file will arrive as a separate email message with its name as the
subject.  But if you:

  send /mail:somebody@xyz.com /subject:{Here is a file} *.txt

Then each file message will have the same subject, which is probably not what
you want.  You can get around this with constructions like:

  send /mail:somebody@xyz.com /subject:{Here is \v(filename)} *.txt

which embed the filename in the subject.

The MOVE, CSEND, MAIL, and RESEND commands now also accept the same switches.
And the switches are also operative when sending from a SEND-LIST (see "Using
C-Kermit", 2nd Ed, pp.191-192), so, for example, it is now possible to SEND
/PRINT or SEND /MAIL from a SEND-LIST.

The MSEND and MMOVE commands also take switches, but not all of them.  With
these commands, which take an arbitrary list of filespecs, you can use
/BINARY, /DELETE, /MAIL, /PRINT, /PROTOCOL, /QUIET, /RECOVER, and /TEXT (and
/IMAGE or /LABELED, depending on the platform).  MMOVE is equivalent to MSEND
/DELETE.  (If you want to send a group of files, but in mixed transfer modes,
and per-file as-names, use ADD SEND-LIST and then SEND.)

The MSEND/MMOVE switches come before the filenames, and apply to all of them:

  msend /print /text *.log oofa.txt /etc/motd

If you type any of these commands (SEND, CSEND, MSEND, etc) followed by a
question mark (?), you will see a list of the switches you can use.  If you
want to see a list of filenames, you'll need to type something like "send ./?"
(UNIX, OS/2, Windows, etc), or "send []?" (VMS), etc.  Of course, you can also
type pieces of a filename (anything that does not start with "/") and then "?"
to get a list of filenames that start that way; e.g. "send x.?"  still works
as before.

In UNIX, where "/" is also the directory separator, there is usually no
ambiguity between a fully-specified pathname and a switch, except when a file
in the root directory has the same name as a switch (as noted in section 1.5):

  send /etc/motd                        ; Works as expected
  send /command                         ; ???

The second example assumes that "/command" is a switch, not a file.  To
actually send a file called "command" in the root directory, use:

  send {/command}

or other system-dependent forms such as //command, /./command, c:/command, etc.

4.7.2. GET Switches

Without switches, the GET command still works about the same as before:

  get oofa.txt                          ; GET a single file
  get oofa.*                            ; GET multiple files

However, the mechanism for including an "as-name" has changed.  Previously,
in order to include an as-name, you were required to use the "multiline" form
of GET:

  get
  <remote-filespec>
  <local-name>

This was because the remote filespec might contain spaces, and so there would
be no good way of telling where it ended and where the local name began, e.g:

  get profile exec a foo

But now since we can use {braces} for grouping, we don't need the multiline
GET form any more, and in fact, support for it has been removed.  If you give
a GET command by itself on a line, it fails and an error message is printed.
The new form is:

  GET [ switches... ] remote-name [ local-name ]

If the remote-name or local-name contains spaces, they must be enclosed in
braces:

  get {profile exec a} foo
  get oofa.txt {~/My Files/Oofa text}

If you want to give a list of remote file specifications, use the MGET
command:

  MGET [ switches... ] remote-name [ remote-name [ remote-name ... ] ]

Now you can also include modifier switches may be included between "get"
or "mget" and the remote-name; most of the same switches as SEND:

  /AS-NAME:text
    Specifies "text" as the name to store the incoming file under.  (This
    switch is not available for MGET.)  You can also still specify the 
    as-name as the second filename on the GET command line.  The following 
    two commands are equivalent:

      get oofa.txt oofa.new
      get /as:oofa.new oofa.txt

  /BINARY
    Forces this transfer to take place in binary mode without affecting the
    global transfer mode.  Example:

      set file type text      ; Set global transfer mode to text
      get /binary oofa.zip    ; get a file in binary mode
      get oofa.txt            ; This one is transferred in text mode

    This works only if (a) the server's TRANSFER MODE is MANUAL, and (b) the
    server support the "whatami" feature; see "Using C-Kermit", 2nd Ed, p.236.
    The client can force the server into manual transfer mode with REMOTE SET
    TRANSFER MODE MANUAL.

  /COMMAND
    GET /COMMAND is equivalent to CGET (section 4.2) -- it says to receive
    the file into the standard input of a command, rather than saving it on
    disk.  The /AS-NAME or the second "filename" on the GET command line is
    interpreted as the name of a command.  Examples:

      get /command sunday.txt {grep Sunday oofa.txt}
      get /command /as-name:{grep Sunday oofa.txt} sunday.txt
      get /bin /command {!gunzip -c | tar xf -} {tar cf - . | gzip -c} 
    
  /DELETE
    Asks the Kermit server to delete the file (or each file in the group)
    after it has been transferred successfully (but not to delete it if it
    was not sent successfully).  GET /DELETE is equivalent to RETRIEVE.
    Example:

      get /delete *.log

  /FILENAMES:{CONVERTED,LITERAL}
    Use this switch to override the current global SET FILE NAMES setting
    for this transfer only.

  /FILTER:<command>
    This specifies a filter to pass the incoming file through before writing
    to disk.  See the section on file-transfer pipes and filters.  The /FILTER
    switch applies only to the file-transfer command it is given with; it does
    not affect the global RECEIVE FILTER setting, if any.

  /IMAGE
    VMS: Transfer in image mode.  Non-VMS: same as /BINARY.

  /LABELED
    VMS and OS/2 only: Specifies labeled transfer mode.

  /PATHNAMES:{OFF,ABSOLUTE,RELATIVE}
    Use this switch to override the current global SET RECEIVE PATHNAMES
    setting for this transfer only.  /PATHNAMES:ABSOLUTE or RELATIVE also sets
    /FILENAMES:LITERAL (also for this transfer only) since incoming pathnames
    would not be treated as pathnames otherwise.

  /QUIET
    When sending in local mode, this suppresses the file-transfer display.

  /RECOVER
    Used to recover from a previously interrupted transfer; GET /RECOVER
    is equivalent REGET.  Works only in binary mode.
    
  /RECURSIVE
    Tells the server that the GET file specification applies recursively.
    This switch also automatically sets /PATHNAMES:RELATIVE.  When used in
    conjunction with /DELETE, this "moves" a directory tree from the server's
    computer to the client's (except that only regular files are deleted from
    the server's computer, not directories; thus the original directories will
    be left, but will contain no files).

  /TEXT
    Performs this transfer in text mode without affecting the global
    transfer mode.  Important: Also see the comments under GET /BINARY.

The /MAIL and /PRINT options are not available, but you can use /COMMAND
to achieve the same effect, as in these UNIX examples:

  get /command oofa.txt {mail kermit@columbia.edu}
  get /command oofa.txt lpr

In OS/2 or Windows, you can GET and print like this:    

  get oofa.txt prn

The CGET, REGET, RETRIEVE commands also accept the same switches as GET.
CGET automatically sets /COMMAND; REGET automatically sets /RECOVER, and
RETRIEVE automatically sets /DELETE.

4.7.3. RECEIVE Switches

Without switches, the RECEIVE command still works as before:

  receive            ; Receives files under their own names
  receive /tmp       ; Ditto, but into the /tmp directory
  r                  ; Same as "receive"
  receive foo.txt    ; Receives a file and renames to foo.txt

Now you can also include modifier switches may be included between "receive"
and the as-name; most of the same switches as GET:

  /AS-NAME:text
    Specifies "text" as the name to store the incoming file under.
    You can also still specify the as-name as a filename on the
    command line.  The following two commands are equivalent:
      r oofa.new
      r /as:oofa.new

  /BINARY
    Performs this transfer in binary mode without affecting the global
    transfer mode.  NOTE: This does not override the incoming filetype (as
    it does with GET), so this switch is useful only if ATTRIBUTE TYPE is
    OFF, or if the other Kermit does not send a TYPE (text or binary)
    attribute.

  /COMMAND
    RECEIVE /COMMAND is equivalent to CRECEIVE (section 4.2) -- it says to
    receive the file into the standard input of a command, rather than saving
    it on disk.  The /AS-NAME or the "filename" on the RECEIVE command line
    is interpreted as the name of a command.
    
      r /command {grep Sunday oofa.txt}
      r /command /as-name:{grep Sunday oofa.txt}
      r /bin /command {tar cf - . | gzip -c} 
    
  /FILENAMES:{CONVERTED,LITERAL}
    Use this switch to override the current global SET FILE NAMES setting
    for this transfer only.

  /FILTER:<command>
    This specifies a filter to pass the incoming file through before writing
    to disk.  See the section on file-transfer pipes and filters.  The /FILTER
    switch applies only to the file-transfer command it is given with; it does
    not affect the global RECEIVE FILTER setting, if any.

  /IMAGE
    VMS: Transfer in image mode.  Non-VMS: same as /BINARY.
    See comments under RECEIVE /BINARY.

  /LABELED
    VMS and OS/2 only: Specifies labeled transfer mode.
    See comments under RECEIVE /BINARY.

  /PATHNAMES:{ON,OFF}
    Use this switch to override the current global SET RECEIVE PATHNAMES
    setting for this transfer only.  /PATHNAMES:ON also sets
    /FILENAMES:LITERAL (for this transfer only) since pathnames would not
    be sent otherwise.

  /QUIET
    When sending in local mode, this suppresses the file-transfer display.

  /TEXT
    Performs this transfer in text mode without affecting the global
    transfer mode.  See comments under RECEIVE /BINARY.

The /MAIL and /PRINT options are not available, but you can use /COMMAND
to achieve the same effect, as in these UNIX examples:

  r /command {mail kermit@columbia.edu}
  r /command lpr

In OS/2 or Windows, you can RECEIVE and print like this:    

  receive prn

The CRECEIVE command now also accepts the same switches.

4.8. Kermit Protocol Improvements

4.8.1. Multiple Attribute Packets

C-Kermit 6.1 now more than one Attribute packet if a file's attributes do not
fit into a single packet of the negotiated length.  If a particular attribute
(such as file creation date-time) does not fit within the negotiated length
(which will only happen when the negotiated length is around 20 or less), that
attribute is not sent at all.

4.8.2. Very Short Packets

There are certain situations where extremely short packets must be used;
20 or 30 bytes at most.  This can happen when one or more devices along the
communication path have very small buffers and lack an effective means of
flow control.  Examples are sometimes cited involving radio modems.

When the maximum packet length is shorter than certain packets that would be
sent, those packets are either truncated or else broken up into multiple
packets.  Specifically:

 1. Parameter negotiation packets (I, S, and their ACKs) are truncated to
    the negotiated length.  Any parameters that do not fit are reset to
    their default values.  There is no provision in the Kermit protocol for
    fragmentation and reassembly of parameter strings.

 2. File header packets (containing the filename) are simply truncated.
    There is no provision in the Kermit protocol for fragmentation and
    reassembly of filenames.

 3. Attribute packets are fragmented and reassembled as described in 4.8.1
    without loss of data, except in case a field will not fit at all in
    the negotiated length (the longest attribute is usually the date and
    time of file creation/modification) because of the rule that attributes
    may not be broken across packets.

 4. Data packets and other packets are unaffected -- they can be as short
    as they need to be, within reason.

4.9. Wildcard / File Group Expansion

4.9.1. In UNIX C-Kermit

You may now "send xxx" where "xxx" is a directory name, and this will send all
the files from the directory xxx, as if you had typed "send xxx/*".  You can
also use the special shorthand "send ." to send all the files from the
current directory.

When choosing Kermit to expand wildcards, rather than the shell, you can
choose whether "dot files" -- files whose names begin with ".", which are
normally "invisible" -- should be matched:

  SET WILD KERMIT /NO-MATCH-DOT-FILES (this is the default)
  SET WILD KERMIT /MATCH-DOT-FILES    (this allows matching of "." files)

4.10. Additional Pathname Controls

In version 6.0 and earlier, C-Kermit's SET { SEND, RECEIVE } PATHNAMES command
had only ON and OFF as options.  In version 6.1, there are more choices:

SET SEND PATHNAMES OFF
  When sending a file, strip all disk/directory information from the name.
  Example: "send /usr/olga/letters/oofa.txt" sends the file as "oofa.txt".
  This applies to actual filenames, not to any as-name you might specify.

SET SEND PATHNAMES RELATIVE
  When sending a file, leave the pathname on as given.  For example, if your
  current directory is /usr/olga, "send letters/oofa.txt" sends the file as
  "letters/oofa.txt", not "/usr/olga/letters/oofa.txt" or "letters.txt".

SET SEND PATHNAMES ABSOLUTE
  When sending a file, convert its name to the full, absolute local pathname.
  For example, if your current directory is /usr/olga, "send letters/oofa.txt"
  sends the file as "/usr/olga/letters/oofa.txt".  NOTE: Even with this
  setting, device and/or node names are not included.  For example, in VMS,
  any node or device name is stripped; in Windows or OS/2, any disk letter
  is stripped.  

SET RECEIVE PATHNAMES OFF
  When receiving a file, strip all disk/directory information from the name
  before attempting to store it.  This applies to incoming filename, not to
  any as-name you might specify.  Example: If a file arrives under the name
  "/usr/olga/letters/oofa.txt" it is stored simply as "oofa.txt" in your
  download directory or, if no download directory has been specified, in your
  current directory.

SET RECEIVE PATHNAMES RELATIVE
  When receiving a file, leave the pathname on as it appears in the incoming
  name, but if the incoming name appears to be absolute, make it relative to
  your current or download directory.  Examples:
  
    "oofa.txt" is stored as "oofa.txt".

    "letters/oofa.txt" is stored as "letters/oofa.txt"; the "letters"
    subdirectory is created if it does not already exist.

    "/usr/olga/letters/oofa.txt" is stored as "usr/olga/letters/oofa.txt"
    in your current or download directory, and the "usr", "usr/olga", etc,
    directories are created if they do not exist.

SET RECEIVE PATHNAMES ABSOLUTE
  The incoming filename is used as given.  Thus it cannot be stored unless the
  given path (if any) already exists or can be created.  In this case, node,
  device, or disk designations are NOT stripped, since they most likely
  were given explicitly by the user as an as-name, meant to be used as given.

Set FILE NAMES CONVERTED now also affects pathnames too.  When PATHNAMES are
RELATIVE or ABSOLUTE and FILE NAMES are CONVERTED, the file sender converts
its native directory-name format to UNIX format, and the file receiver
converts from UNIX format to its native one; thus UNIX format is the common
intermediate representation for directory hierarchies, as it is in the
ZIP/UNZIP programs (which is why ZIP archives are transportable among, UNIX,
DOS, and VMS).

Here's an example in which a file is sent from Windows to UNIX with relative
pathnames and FILE NAMES CONVERTED:

  Source name                Intermediate name      Destination Name
  C:\K95\TMP\OOFA.TXT        K95/TMP/OOFA.TXT       tmp/oofa.txt

In a more complicated example, we send the same file from Windows to VMS:

  Source name                Intermediate name      Destination Name
  C:\K95\TMP\OOFA.TXT        K95/TMP/OOFA.TXT       [.K95.TMP]OOFA.TXT

(Note that disk letters and device designations are always stripped.)

As you can imagine, as more and more directory formats are considered, this
approach keeps matters simple: on each platform, Kermit must know only its
own local format and the common intermediate one.  In most cases, the receiver
can detect which format is used automatically.

4.11. Recursive SEND: Sending Directory Trees

C-Kermit 6.1 in selected versions (UNIX, VMS, VOS, AOS/VS, Windows, and OS/2
at this writing) now permits the SEND command to traverse directories
"recursively" if you ask it to; that is, to send files from the current or
specified directory and all of its inferior or descendent directories too.

This feature is new to UNIX, Windows, VOS, Windows, and OS/2.  VMS and AOS/VS
have always included "wildcard" or "template" characters that allow this, and
in this case, recursive directory traversal happens behind Kermit's back,
i.e. Kermit does not have to do it itself (in VMS, the notation is "[...]"  or
"[directory...]"; in AOS/VS is "#").

4.11.1. Command-Line Options

To descend a directory tree when sending files, use the -L command-line option
to indicate that the send operation is to be recursive, and include a name or
pattern to be sent.  When giving a pattern, you should enclose it in quotes to
prevent the shell from expanding it.  Examples:

  $ kermit -Ls "/usr/olga/*" # send all of Olga's files in all her directories
  $ kermit -Ls foo.txt       # send all foo.txt files in this directory tree
  $ kermit -Ls "*.txt"       # send all .txt files in this directory tree
  $ kermit -Ls "letters/*"   # send all files in the letters directory tree
  $ kermit -Ls letters       # send all files in the letters directory tree
  $ kermit -Ls "*"           # send all files in this directory tree
  $ kermit -Ls .             # UNIX only: send all files in this directory tree
  $ kermit -s .              # UNIX only: a filename of . implies -L

If you let the shell expand wildcards, Kermit only sends files whose names
match files in the current or given directory, because the shell replaces an
unquoted wildcard expression with the list of matching files -- and the shell
does not build recursive lists.  Note that the "." notation for the tree
rooted at the current directory is allowed only in UNIX, since in Windows and
OS/2, it means "*.*" (nonrecursive).

4.11.2. The SEND /RECURSIVE Command

If you include the /RECURSIVE switch in a SEND (or MOVE, or similar) command,
it means to descend the current or specified directory tree searching for
files whose names match the given name or pattern.  Since this is not terribly
useful unless you also include pathnames with the outbound files, the
/RECURSIVE switch also includes an implicit /PATHNAMES:RELATIVE switch (which
you can undo by including an explicit /PATHNAMES switch after the /RECURSIVE
switch).

Examples:

SEND /RECURSIVE *
  Sends all of the files in the current directory and all the files in 
  all of its subdirectories, and all of their subdirectories, etc, including
  their relative pathnames.  Empty directories are not sent.

SEND /RECURSIVE /PATHNAMES:ABSOLUTE *
  Sends all of the files in the current directory and all the files in 
  all of its subdirectories, and all of their subdirectories, etc, including
  their absolute pathnames.

SEND /RECURSIVE /PATHNAMES:OFF *
  Sends all of the files in the current directory and all the files in 
  all of its subdirectories, and all of their subdirectories, etc, without
  pathnames.

SEND /RECURSIVE /usr/olga/*
  Sends all of the files in the /usr/olga directory and all the files in 
  all of its subdirectories, and all of their subdirectories, etc.

SEND /RECURSIVE /usr/olga  (or /usr/olga/)
  Same as above.  If the name is a directory name (with or without a
  trailing slash), its files are sent, and those of its subdirectories,
  and their subdirectories, etc (see section 4.9).

SEND /RECURSIVE /TEXT /usr/olga/*.txt
  As above, but only files whose names end with ".txt" are sent, and they
  are sent in text mode.

SEND /RECURSIVE .
  UNIX only: Sends all of the files in the current directory and all of its
  subdirectories, etc (section 4.9).
  
SEND .
  UNIX only: If the filename is "." (by itself), /RECURSIVE is implied.

The /RECURSIVE switch is different from other switches in that its effect is
immediate (but still local to the command in which it is given), because it
determines how filenames are to be parsed.  For example, "send *.txt" fails
with a parse error ("No files match") if there are no *.txt files in the
current directory, but "send /recursive *.txt" succeeds if there are any
".txt" files in any subdirectories of the current directory.

The /RECURSIVE switch also affects the file lists displayed if you type "?"
in a filename field.  "send ./?" lists the regular files in the current
directory, but "send /recursive ./?" lists the entire directory tree rooted
at the current directory.

Again, the normal method for transferring directory trees uses relative
pathnames, and this is the default when the sender has been given the
/RECURSIVE switch.  The receiver, however, must be told also:

  set receive pathnames relative  ; Applies from now
  receive

or:

  receive /pathnames:relative     ; Applies only to this RECEIVE command

But what happens if a file arrives that has an absolute pathname, when the
receiver has been told to use only relative pathnames?  As a security
precaution, in this case the receiver treats the name as if it was relative.
For example, if a file arrives as:

  /usr/olga/oofa.txt

The receiver creates a "usr" subdirectory in its current directory, and
then an "olga" subdirectory under the "usr" subdirectory in which to store
the incoming file.

Suppose, however there is a sequence of directories:

  /usr/olga/a/b/c/d/

in which "a" contains nothing but a subdirectory "b", which in turn contains
nothing but a subdirectory "c", which in turn contains nothing but a
subdirectory "d", which contains nothing at all.  Thus there are no files in
the "/usr/olga/a/" tree, and so it is not sent, and therefore it is not
reproduced on the target computer.

4.11.3. New and Changed Functions

C-Kermit 6.1 adds the following functions:

\ffiles(pattern)
  This function has been changed to match only regular files in the current
  or given directory.

\fdirectories(pattern)
  Returns the number of directories that match the given pattern.
  If the pattern does not include a directory, then the search is performed
  in the current directory.

\frfiles(pattern)
  Returns the number of files in the current or given directory and all of
  its subdirectories, and their subdirectories, etc, that match the given
  pattern.

\frdirectories(pattern)
  Returns the number of directories in the current or given directory and all
  of its subdirectories, and their subdirectories, etc, that match the given
  pattern.

Each of these functions builds up a list of files to be returned by the
\fnextfile() function, just as \ffiles() always has done.

Here's an example that builds and prints a list of all the file whose names
end in .txt in the current directory and all its descendents:

  asg \%n \frfiles(*.txt)
  declare \&a[\%n]
  for \%i 1 \%n 1 {
      asg \&a[\%i] \fnextfile()
      echo \flpad(\%i,4). "\&a[\%i]"
  }

As noted elsewhere, the file lists built by \ffiles(), \frfiles(), etc, are
now "safe" in the sense that SEND and other file-related commands can now
reference \fnextfile() without resetting the list:

  set send pathnames relative
  for \%i 1 \frfiles(*.txt) 1 {
      asg \%a \fnextfile()
      echo Sending \%a...
      send \%a
      if fail break
  }

Copying to an array is no longer necessary.

4.11.4. Moving Directory Trees Between Like Systems

Normal filename and path handling requires that pathnames be stripped from
inbound as well as outbound files.  This applies also to recursive transfers.
Thus if you tell C-Kermit to "send /recursive oofa.txt", then all oofa.txt
files in the current directory tree are sent with the same name, "oofa.txt".
Thus they are all stored in the same destination directory, either overwriting
each other, or else renamed according to the receiver's FILE COLLISION setting.

As noted in section 4.10, you can (and in this case, probably should) elect
to send files with full or relative pathnames when performing recursive
transfers, and to use the pathnames during file reception for storing the
incoming files.

In the most typical application, we use C-Kermit to transfer a directory tree
from one computer to another; that is, to replicate the file sender's
arrangement of files and directories on the file receiver's computer.
Normally this would be done using relative pathnames, since the user IDs
might not be identical on the two computers.  Let's say both computers are
UNIX based, running C-Kermit 6.1 or later.  On the sending computer
(leaving out the connection details, etc):

  $ kermit
  C-Kermit> cd /usr/olga
  C-Kermit> send /recursive .

On the receiving computer:

  $ kermit
  C-Kermit> cd /home/ivan/
  C-Kermit> mkdir olgas-files
  C-Kermit> cd olgas-files
  C-Kermit> receive /pathnames:relative ; (abbreviate "r /pa:r")

Each Kermit program recognizes that the other is running under UNIX and
switches to binary mode and literal filenames automatically.  Directories
are automatically created on the receiving system as needed.  File dates
and permissions are automatically reproduced from source to destination.

4.11.6. Moving Directory Trees Between Unlike Systems

There are several difficulties with recursive transfers between unlike
systems:

 . File formats can be different, especially text files character sets and
   record formats.  This can now be handled by using SET FILE PATTERN,
   SET FILE TEXT-PATTERNS, and SET FILE BINARY-PATTERNS (Section 4.3).

 . File naming conventions are different.  For example, one system might allow
   (and use) longer filenames than the other.  You can tell Kermit how to
   handle file names with the normal "set file names" and "set file
   collision" mechanisms.  Most modern Kermits are fairly tolerant of illegal
   filenames and should not fail simply because of an incoming filename;
   rather, it will do its best to convert it to a recognizable and unique
   legal filename.

 . Directory notations can be different, e.g. backslashes instead of slashes,
   brackets, parentheses, spaces, etc.  But this is now handled by converting
   pathnames to a standard format during transfer (Section 4.10).

So now, for the first time, it is possible to send directory trees among
any combination of UNIX, DOS, Windows, OS/2, VMS, AOS/VS, etc.  Here's an
example sending files from an HP-UX system (where text files are encoded in
the HP Roman8 character set) to a PC with K95 (where text files are encoded
in CP850):

 Sender:
  cd xxx                           ; CD to root of source tree
  set file type binary             ; Default transfer mode
  set file character-set hp-roman8 ; Local character set for text files
  set xfer character-set latin1    ; Transfer character set
  set file patterns on             ; Enable automatic file-type switching...
  set file binary-patterns *.Z *.gz *.o  ; based on these patterns...
  set file text-patterns *.txt *.c *.h   ; for binary and text files.
  send /recursive *                ; Send all the file in this directory tree

 Receiver:
  cd yyy                           ; CD to root of destination tree
  set file character-set cp850     ; Local character set for text files
  receive /pathnames:relative      ; Receive with pathnames

 Notes:
 . Replace "xxx" and "yyy" with the desired directories.
 . Replace the file character sets appropriately.
 . Change the patterns as needed (or just use the built-in default lists).
 . SEND /RECURSIVE also implies /PATHNAMES:RELATIVE.
 . The file sender tells the file receiver the transfer mode of each file.
 . The file sender tells the file receiver the transfer character set.
 . By default, destination file dates will be the same as on the source.
 . Many of the settings shown might already be set by default.
 . See sections 4.3, 4.10, and 4.15 for additional explanation.

If you are refreshing an existing directory on the destination computer,
use "set file collision update" or other appropriate file collision option
to handle filename collisions.

An interrupted directory-tree transfer can be resumed by using SEND /RECOVER
(= RESEND) rather than SEND.

4.12. Where Did My File Go?

Now that Kermit can be started by clicking on desktop icons (thus obscuring
the concept of "current directory"), and can have a download directory, and
can create directories for incoming files on the fly, etc, sometimes it is
easy to lose a file after transfer.  Of course, if you keep a transaction log:

  LOG TRANSACTIONS

it will record the fate and final resting place of each file.  But in case
you did not keep a log, the new command:

  WHERE

added in C-Kermit 6.1, gives you as much information as it has about the
locations of the last files transferred, including the pathname reported by
the receiving Kermit, if any, when C-Kermit is the sender.  This information
was also added to SHOW FILE in somewhat less detail.

4.13. File Output Buffer Control

(UNIX only).  The new command SET FILE OUTPUT lets you control how incoming
files are written to disk:

SET FILE OUTPUT BUFFERED [ <size> ]
  Chooses buffered file output; this is the default.  UNIX does its normal
  sort of disk buffering.  The optional <size> specifies Kermit's own file
  output buffer size, and therefore the frequency of disk accesses (write()
  system calls) -- the bigger the size, the fewer the disk accesses.

SET FILE OUTPUT UNBUFFERED [ <size> ]
  This forces each file output write() call to actually commit the data to
  disk immediately.  Choosing this option will usually slow file reception
  down.
  
SET FILE OUTPUT BLOCKING
  Write() calls should not return until they are complete.  This is the normal
  setting, and it lets Kermit detect disk-write errors immediately.

SET FILE OUTPUT NONBLOCKING
  Write() calls should return immediately.  This can speed up file reception,
  but also delay the detection of disk-write errors.

Experimentation with these parameters should be harmless, and might (or might
not) have a perceptible, even dramatic, effect on performance.

4.14. Improved Responsiveness

In version 6.1, C-Kermit's file-transfer protocol engine has been tuned
for additional speed and responsiveness.

 . Binary-mode transfers over 8-bit connections, a very common case, are 
   now handled in a special way that minimizes overhead.

 . SET TRANSFER CRC-CALCULATION is now OFF by default, rather than ON.
   (This affects only the overall per-transfer CRC, \v(crc16), not the
   per-packet CRCs)

 . Connection loss during file transfer is now detected immediately in most
   cases (on Internet connections, on serial connections when CARRIER-WATCH
   is not set to OFF).

4.15. DOUBLING AND IGNORING CHARACTERS FOR TRANSPARENCY

The following commands were added in 6.1, primarily to allow successful
file transfer through ARPAnet TACs and with Honeywell DPS6 systems, but can
be used in any setting where they might be needed:

SET SEND DOUBLE-CHAR { [ <char> [ <char> [ ... ] ] ], NONE }
  Tells C-Kermit to double the specified characters (use decimal notation)
  in packets that it sends.  For example, if you are sending files through
  a device that uses @ as an escape character, but allows you to send a
  single copy of @ through by doubling it, use "set send double 64".

SET RECEIVE IGNORE-CHAR [ <char> [ <char> [ ... ] ] ]
  Tells C-Kermit to ignore the specified character(s) in incoming packets.
  Use this, for example, when something between the sender and receiver is
  inserting linefeeds for wrapping, NULs for padding, etc.

4.16. New File-Transfer Display Formats

SET TRANSFER DISPLAY { BRIEF, CRT, FULLSCREEN, NONE, SERIAL }

BRIEF is the new one.  This writes one line to the screen per file, showing
the file's name, transfer mode, size, the status of the transfer, and when the
transfer is successful, the effective data rate in characters per second (CPS).
Example:

 SENDING ckcfn3.o (binary) (59216 bytes): OK (0.104 sec, 570206 cps)
 SENDING ckcfns.o (binary) (114436 bytes): OK (0.148 sec, 772006 cps)
 SENDING ckcmai.c (text) (79147 bytes): OK (0.180 sec, 438543 cps)
 SENDING ckcmai.o (binary) (35396 bytes): OK (0.060 sec, 587494 cps)
 SENDING ckcnet.o (binary) (62772 bytes): REFUSED
 SENDING ckcpro.o (binary) (121448 bytes): OK (0.173 sec, 703928 cps)
 SENDING ckcpro.w (text) (63687 bytes): OK (0.141 sec, 453059 cps)
 SENDING makefile (text) (186636 bytes): OK (0.444 sec, 420471 cps)
 SENDING wermit (binary) (1064960 bytes): OK (2.207 sec, 482477 cps)

Note that transfer times are now obtained in fractional seconds, rather than
whole seconds, so the CPS figures are now far more accurate (the display
shows 3 decimal places, but the actual figure is generally precise to the
microsecond).

4.17. New Transaction Log Format

The new command:

  SET TRANSACTION-LOG { VERBOSE, BRIEF [ <separator> ] }

lets you choose the format of the transaction log.  VERBOSE (the default)
indicates the traditional format described in the book.  BRIEF is new; this
chooses a one-line per file format suitable for direct importation into
databases like Informix, Oracle, or Sybase, in which:

 . Each record has 8 fields.
 . Fields are separated by a non-alphanumeric separator character.
 . The default separator character is comma (,).
 . Any field containing the separator character is enclosed in doublequotes.
 . The final field is enclosed in doublequotes.

The fields are:

  1. Date in yyyymmdd format
  2. Time in hh:mm:ss format
  3. Action: SEND or RECV
  4. The local filename
  5. The size of the file
  6. The transfer mode (text, binary, image, labeled)
  7. The status of the transfer: OK or FAILED
  8. Additional status-dependent info, in doublequotes.

Example:

  19980208,12:08:52,RECV,/u/olga/oofa.txt,5246,text,OK,"0.284sec 18443cps"
  19980208,12:09:31,SEND,/u/olga/oofa.exe,32768,binary,OK,"1.243sec 26362cps"
  19980208,12:10:02,SEND,"/u/olga/a,b",10130,text,FAILED,"Refused: date"

Note how the filename is enclosed in doublequotes in the final example,
because it contains a comma.

To obtain BRIEF format, you must give the SET TRANSACTION-LOG BRIEF command
before the LOG TRANSACTIONS command.  (If you give them in the opposite order,
a heading is written to the log by the LOG command.)

4.18. Unprefixing NUL

As of 6.1.193 Alpha.10, C-Kermit can finally send and receive file-transfer
packets in which NUL (ASCII 0) is unprefixed (no more NUL-terminated
packets!).  NUL is, of course, extremely prevalent in binary files such as
executables, and this has been a significant source of packet overhead.  For
example, when transferring itself (the SunOS C-Kermit executable) with minimal
prefixing and 9000-byte packets, we see:

  File size:                       1064960
  Packet chars with 0 prefixed:    1199629  overhead = 12.65%
  Packet chars with 0 unprefixed:  1062393  overhead = -0.03%

Transfer rates go up accordingly, not only because of the reduced amount of
i/o, but also because less computation is required on each end.

For now, unprefixed 0's can be sent only between two copies of C-Kermit 6.1
Alpha.10.  Later this will also be possible in Kermit 95 and MS-DOS Kermit.

4.19. Clear-Channel Protocol

Now that C-Kermit itself is capable of sending and receiving any byte at all
on a clear channel (section 4.18), it is, for the first time, in a position to
negotiate a clear channel with the other Kermit, giving it permission (but not
requiring it) to unprefix any and all characters that it knows are safe.  In
general this means all but the Kermit start-of-packet character (normally
Ctrl-A), Carriage Return (not only Kermit's end-of-packet character, but also
treated specially on Telnet NVT links), and IAC (255, also special to Telnet).

By default, C-Kermit will say it has a clear channel only if it has opened a
TCP socket.  Since the Kermit program on the far end of a TCP/IP connection
generally does not know it has a TCP/IP connection, it will not announce a
clear channel unless it has been told to do so.  The command is:

  SET CLEAR-CHANNEL { ON, OFF, AUTO }

AUTO is the default, meaning that the clear-channel status is determined
automatically from the type of connection.  ON means to announce a clear
channel, OFF means not to announce it.  Use SHOW STREAMING (Section 4.20)
to see the current CLEAR-CHANNEL status.

CLEAR-CHANNEL is also set if you tell C-Kermit to SET RELIABLE ON, or if
start C-Kermit with the -I switch (see Section 4.20).

Whenever a clear channel is negotiated, the resulting control-character
unprefixing is "sticky"; that is, it remains in effect after the transfer so
you can use SHOW CONTROL to see what was negotiated.

The advantage of the clear channel feature is that it can make file transfers
go faster automatically.  The disadvantage would be file-transfer failures if
the channel is not truly clear.  If a file transfer fails on a TCP/IP
connection, use SHOW CONTROL to check whether control characters became
unprefixed as a result of protocol negotiations, and/or SHOW STREAMING
(Section 4.20) to see if "clearchannel" was negotiated.  If this happened,
use SET CLEAR-CHANNEL OFF and SET PREFIXING CAUTIOUS (or whatever) to prevent
it from happening again.

4.20. Streaming Protocol

A new Kermit protocol option called "streaming" was added in C-Kermit 6.1.
The idea is that if the two Kermit partners have a reliable transport (such as
TCP/IP or X.25) between them, then there is no need to send ACKs for Data
packets, or NAKs, since a reliable transport will, by definition, deliver all
packets in order and undamaged.  On such a connection, streaming cuts down not
only on Kermit program overhead (switching back and forth between reading and
sending packets), but also tends to make the underlying transport use itself
more efficiently (e.g. by defeating the Nagle algorithm and/or Delayed ACK
stratagem of the TCP layer).

The trick is knowing when we can stream:

 a. If C-Kermit has opened a TCP socket, it will offer to stream.

 b. If C-Kermit has been started with the -I (uppercase) option, or if it
    has been told to SET RELIABLE ON, it will offer to stream.  (Note: this
    also results in a Clear-Channel announcement if CLEAR-CHANNEL is
    set to AUTO; see Section 4.19.)
    
(b) is necessary when C-Kermit is on the far end (e.g.) of a Telnet or Rlogin
connection and does not know it.  (b) is NOT necessary when "remote" C-Kermit
has been told to "set host * <port>" and the client made a direct connection
to its TCP port (because then it knows it has a TCP connection).

When BOTH Kermits offer to stream, then they stream; otherwise they don't.
Thus streaming-capable Kermit programs interoperate automatically and
transparently with nonstreaming ones.  If the two Kermits do agree to stream,
you'll see the word "STREAMING" on the fullscreen file-transfer display.  You
can also find out afterwards with the STATISTICS or SHOW STREAMING commands.

Streaming is like using an infinite window size, with no timeouts, and no
tolerance for transmission errors (since there shouldn't be any).  It relies
on the underlying transport for flow control, error correction, timeouts, and
retransmission.  Thus it is very suitable for use on TCP/IP connections,
especially slow or bursty ones, since Kermit's packet timeouts won't interfere
with the transfer -- each packet takes as long to reach its destination as it
takes TCP to deliver it.  If TCP can't deliver the packet within its own
timeout period (over which Kermit has no control), it signals a fatal error.
Just like FTP.

Streaming goes much faster than non-streaming when a relatively small packet
length is used, and it tends to go faster than non-streaming with even the
longest packet lengths.  The Kermit window size is irrelevant to streaming
protocol, but still might affect performance in small ways since it can result
in different paths through the code.

The definition of "reliable transport" does not necessarily demand 8-bit and
control-character transparency.  Streaming can work with parity and/or
control-character unprefixing just as well (but not as fast) as without them.

Maximum performance -- comparable to and often exceeding FTP -- is achieved 
on socket-to-socket connections (in which the considerable overhead of the
terminal driver and/or Telnet or Rlogin server is eliminated) with long
packets and the new "brief" file-transfer display (Section 4.16).

4.20.1. Commands for Streaming

  SET RELIABLE { ON, OFF }

This command has several effects, including:

 . It can affect the timeouts used during normal ACK/NAK protocol.
 . It can affect the clear-channel announcement.
 . It can affect streaming.

If you TELNET or SET HOST somewhere, this includes an implicit SET RELIABLE ON
command.  The -I command-line option is equivalent to SET RELIABLE ON.

  Presently, C-Kermit does not perform the implicit SET RELIABLE ON for X.25
  connections, but it will do so before 6.1 is released.  For now, after
  making an X.25 connection, give an explicit SET RELIABLE ON command.

Since SET RELIABLE ON (and -I) also implies SET CLEAR CHANNEL ON, you might
find that in certain cases you need to tell Kermit that even though the
connection is reliable, it doesn't have a clear channel after all:

  SET CLEAR-CHANNEL OFF
  SET PREFIXING CAUTIOUS ; or whatever...

You can control streaming without affecting the other items with:

  SET STREAMING { ON, OFF, AUTO }

AUTO is the default, meaning streaming will occur if Kermit has made a TCP/IP
connection or if RELIABLE is ON (or it was started with the -I command line
option).  OFF means don't stream; ON means offer to stream no matter what.

4.20.2. Examples of Streaming

Here we look at the use and behavior of streaming on several different kinds
of connections, and compare its performance with non-streaming transfers.

4.20.2.1. Streaming on Socket-to-Socket Connections

Here we get streaming automatically when both Kermit programs are capable of
it, since they both make socket connections.  For example, on the far end:

  C-Kermit> fast
  C-Kermit> set host * 3000
  C-Kermit> server

and on the near end:

  C-Kermit> fast
  C-Kermit> set host foo.bar.xyz.com 3000
  (now give SEND and GET command)

All subsequent file transfers will use streaming automatically.

Here are the results from 84 trials, run on a production network,
disk-to-disk, in which a 1-MB binary file (the SunOS C-Kermit Sparc
executable) was sent from a Sun Sparc-10 with SunOS 4.1.3 to an IBM Power
Server 850 with AIX 4.1, socket-to-socket, over a 10Mbps 10BaseT Ethernet,
using minimal control-character unprefixing, window sizes from 10 to 32, and
packet sizes from 1450 to 9010:

                Streaming    Nonstreaming
  Max CPS         748955        683354
  Min CPS         221522        172491
  Mean CPS        646134        558680
  Median CPS      678043        595874
  Std Dev         101424        111493

Correlations:

  CPS and window size:   -0.036
  CPS and packet length:  0.254
  CPS and streaming:      0.382

Note that the relationship between streaming and throughput is significantly
stronger than that between CPS and window size or packet length.

Also note that this and all other performance measurements in this section
are snapshots in time; the results could be much different at other times when
the load on the systems and/or the network is higher or lower.

In a similar socket-to-socket trial, but this time over a wide-area TCP/IP
connection (from New York City to Logan, Utah, about 2000 miles), the
following results were obtained:

                Streaming    Nonstreaming
  Max CPS         338226        318203
  Min CPS         191659        132314
  Mean CPS        293744        259240
  Median CPS      300845        273271
  Std Dev          41914         52351

Correlations:

  CPS and window size:    0.164
  CPS and packet length:  0.123
  CPS and streaming:      0.346

4.20.2.2. Streaming on Telnet Connections

In this case the local copy of Kermit is told to TELNET or SET HOST, and so it
knows it has a reliable connection and -- unless it has been told not to --
will offer to stream.

The Kermit program on the remote end, however, does not know it has a reliable
connection and so must be told that it does, e.g.:

  kermit -I

(uppercase letter I) or:

  C-Kermit> set reliable on

Since the connection is reliable, it is usually also safe to pick a large
packet length (*) and (though it doesn't matter much, as the statistics show)
a big window size:

  kermit -IQ

("the smart way to start Kermit"; -Q is the command line option for fast
[Quick] protocol settings), or:

  C-Kermit> fast

And, since we have a reliable connection, we'll also get minimal unprefixing
automatically because of the new clear-channel protocol (Section 4.19).  Note:
if the transfer fails, you might need to tell the remote Kermit to "set flow
none", or the local Kermit to prefix Xon, Xoff, and/or some other control
characters, but that's no different from the nonstreaming case.

(*) Certain Telnet servers impose a limit, such as the 4096-byte limit of 
    the SGI IRIX Telnet server; more about this in the next section.

Here are the figures for the same 84 trials between the same Sun and IBM
hosts as in 4.20.2.1, on the same network, but over a Telnet connection rather
than socket-to-socket:

                  Streaming    Nonstreaming
  Max CPS         350088        322523
  Min CPS          95547        173152
  Mean CPS        321372        281830
  Median CPS      342604        291469
  Std Dev          40503         29948

Correlations:

  CPS and window size:    0.001
  CPS and packet length:  0.152
  CPS and streaming:      0.128

Here the effect is not as emphatic as in the socket-to-socket case, yet on 
the whole streaming tends to be beneficial.

4.20.2.3. Streaming with Limited Packet Length

The IRIX telnet server (at least the ones observed in IRIX 5.3 and 6.2) does
not allow Kermit to send packets longer than 4096 bytes.  Thus when sending
from IRIX C-Kermit when it is on the remote end of a Telnet connection, the
packet length must be 4K or less.  Trials in this case (in which packet
lengths range from 1450 to 4000) show a strong advantage for streaming, which
would be evident in any other case where the packet length is restricted, and
stronger the shorter the maximum packet length.

                  Streaming    Nonstreaming
  Max CPS         426187        366870
  Min CPS         407500        276517
  Mean CPS        415226        339168
  Median CPS      414139        343803
  Std Dev           6094         25851

Correlations:

  CPS and window size:    0.116
  CPS and packet length:  0.241
  CPS and streaming:      0.901

4.20.2.4. Streaming on Dialup Connections

Here "dialup" refers to a "direct" dialup connection, not a SLIP or PPP
connection, which is only a particular kind of TCP/IP connection.

Attempt this at your own risk, and then only if (a) you have error-correcting
modems, and (b) the connections between the modems and computers are also
error-free, perfectly flow-controlled, and free of interrupt conflicts.
Streaming can be used effectively and to fairly good advantage on such
connections, but remember that the transfer is fatal if even one error is
detected (also remember that should a binary-mode transfer fail, it can be
recovered from the point of failure with RESEND).

To use streaming on an unreliable connection, you must tell both Kermits that
the connection is reliable:

  kermit -I

or:

  C-Kermit> set reliable on

In this case, it will probably be necessary to prefix some control characters,
for example if your connection is through a terminal server that has an escape
character.  Most Cisco terminal servers, for example, require Ctrl-^ (30, as
well as its high-bit equivalent, 158) to be prefixed.  To unprefix these,
you'll need to defeat the "clear channel" feature:

  C-Kermit> set reliable on
  C-Kermit> set clear-channel off
  C-Kermit> set prefixing none
  C-Kermit> set control prefix 1 13 30 158 ; and whatever else is necessary

Dialup trials were done using fixed large window and packet sizes.  They
compare uploading and downloading of two common types of files, with and
without streaming.  Configuration:

  HP-9000/715/33 -- 57600bps, RTS/CTS -- USR Courier V.34 -- V.34+V.42,
  31200bps -- USR V.34+ Rackmount -- 57600bps, RTS/CTS -- Cisco terminal
  server -- Solaris 2.5.1.  Packet size = 8000, Window Size = 30, Control
  Character Unprefixing Minimal (but including the Cisco escape character).

Since this is not a truly reliable connection, a few trials failed when a bad
packet was received (most likely due to UART overruns); the failure was
graceful and immediate, and the message was informative.  The results of ten
successful trials uploading and downloading the two files with and without
streaming are:

            Streaming..
            Off    On     
   Upload   5194   5565   txt (= C source code, 78K)
            3135   3406   gz  (= gzip file, compressed, 85K)
 Download   5194   5565   txt
            3041   3406   gz            

Each CPS figure is the mean of 10 results.

A brief test was also performed on a LAT-based dialout connection from a VAX
3100 with VMS 5.5 to a USR Courier V.34 connected to a DECserver 700 at 19200
bps.  The 1-MB Sparc executable downloaded from a Sun to the VAX at 1100cps
without streaming and 1900cps with streaming, using 8000-byte packets, 30
window slots, and minimal prefixing in both cases.

4.20.2.5. Streaming on X.25 Connections

We have only limited access to X.25 networks.  One trial was performed in
which the 1MB Solaris 2.4 Sparc executable was transferred over a SunLink X.25
connection; nothing is known about the actual physical connection.  With a
packet length of 8000 and a window size of 30, the file transferred at 6400
cps (using a maximum of 6 window slots).  With the same packet length, but
with streaming, it transferred without mishap at 6710 cps, about 5% faster.

4.20.3. Streaming - Preliminary Conclusions

The results vary with the particular connection, but are good overall.
Although numerous lower-level tricks can be used to improve performance on
specific platforms or connection methods, streaming occurs at a high,
system-independent level of the Kermit protocol and therefore can apply to all
types of platforms and (reliable) connections transparently.

4.21. The TRANSMIT Command

When TRANSMIT ECHO is ON, C-Kermit tries to read back the echo of each
character that is sent.  Prior to C-Kermit 6.1, 1 second was allowed for each
echo to appear; if it didn't show up in a second, the TRANSMIT command would
fail.  Similarly for the TRANSMIT PROMPT character.  However, with today's
congested Internet connections, etc, more time is often needed:

SET TRANSMIT TIMEOUT <number>
  Specifies the number of seconds to wait for an echo or the prompt character;
  the default wait is 1 second.  If you specify 0, the wait is indefinite.
  When a timeout interval of 0 is specified, and a desired echo or prompt does
  not show up, the TRANSMIT command will not terminate until or unless you
  interrupt it with Ctrl-C; use SET TRANSMIT TIMEOUT 0 with caution.

Note: to blast a file out the communications connection without any kind of
echo checking or timeouts or other manner of checking, use:

  SET TRANSMIT ECHO OFF
  SET TRANSMIT PROMPT 0
  TRANSMIT <filename>

(5) CLIENT/SERVER

5.0. Hints

If you use SET SERVER GET-PATH to set up your server, and the GET-PATH does
not include the server's current directory, clients can become quite confused.
For example, "remote dir oofa.txt" shows a file named oofa.txt, but "get
oofa.txt" fails.  In this situation, you should either DISABLE DIR or make
your GET-PATH include current directory.

5.1. New Command-Line Options

The -G command-line option is like -g (GET), except the incoming file is
sent to standard output rather than written to disk.

The -I option is equivalent to SET RELIABLE ON.

The -O option tells C-Kermit to enter server mode but then exit after the
first client operation.

5.2. New Client Commands

BYE and FINISH no longer try to do anything if a connection is not active.
Thus a sequence like "hangup" followed by "bye" or "finish" will no longer get
stuck in a long timeout-and-retransmission cycle, nor will it try to open a
new connection.

REMOTE MKDIR <directory-name>
  Tells the client to ask the server to create a directory with the given
  name, which can be absolute or relative.  The syntax of the directory name
  depends on the Kermit server (see next section); in all cases, it can be in
  the syntax of the system where the server is running (UNIX, VMS, DOS, etc)
  but newer servers also accept UNIX syntax, no matter what the underlying
  platform.  The server will not execute this command if (a) it does not
  understand it, (b) a DISABLE MKDIR command has been given, or (c) a DISABLE
  CWD command has been given; otherwise, the command is executed, but will
  fail if the directory can not be created, in which cases most servers will
  attempt to return a message giving the reason for failure.  The REMOTE MKDIR
  command succeeds if the remote directory is created, or if it already exists
  and therefore does not need to be created, and fails otherwise.

REMOTE RMDIR <directory-name>
  Tells the client to ask the server to remove (delete) a directory with the
  given name.  The same considerations apply as for REMOTE MKDIR.

REMOTE SET FILE INCOMPLETE { DISCARD, KEEP }
  Previously this was only available in its earlier form, REMOTE SET
  INCOMPLETE (no FILE).  The earlier form is still available, but invisible.

REMOTE SET TRANSFER MODE { AUTOMATIC, MANUAL }
  Tells the client to ask the server to set the given file-transfer mode.
  Automatic means (roughly): if the client and the server are running on the
  same kind of computer (e.g. both are on UNIX), then use binary mode
  automatically; if the system types are different, use some other method
  to automatically determine text or binary mode, such as filename pattern
  matching.  MANUAL means, in this context, obey the client's FILE TYPE
  setting (TEXT or BINARY).  Use REMOTE SET TRANSFER MODE MANUAL to give the
  client total control over the transfer mode, e.g. by using GET /BINARY and
  GET /TEXT.  Synonym: REMOTE SET XFER MODE ...

REMOTE QUERY KERMIT function(args...)
  Prior to C-Kermit 6.1, the arguments were not evaluated locally.  Thus it
  was not possible to have the server run the function with client-side
  variables as arguments.  Now:
    define \%a oofa.*
    remote query kermit files(\%a)    ; Client's \%a
    remote query kermit files(\\%a)   ; Server's \%a

5.3. New Server Capabilities

5.3.1. Creating and Removing Directories

The C-Kermit 6.1 server responds to REMOTE MKDIR and REMOTE RMDIR commands.
The directory name may be in either the native format of the computer where
the server is running, or in UNIX format.  For example, a server running on
VMS with a current directory of [IVAN] can accept commands from the client
like:

  remote mkdir olga         ; Makes [IVAN.OLGA] (nonspecific format)
  remote mkdir .olga        ; Makes [IVAN.OLGA] (VMS format without brackets)
  remote mkdir olga/        ; Makes [IVAN.OLGA] (UNIX relative format)
  remote mkdir /ivan/olga   ; Makes [IVAN.OLGA] (UNIX absolute format)
  remote mkdir [ivan.olga]  ; Makes [IVAN.OLGA] (VMS absolute format)
  remote mkdir [.olga]      ; Makes [IVAN.OLGA] (VMS relative format)

5.3.1.1. Creating Directories

If a directory name is given that contains more than one segment that does not
exist, the server attempts to create all the segments.  For example, if the
client says:

  REMOTE MKDIR letters/angry

a "letters" subdirectory is created in the server's current directory if it
does not already exist, and then an "angry" subdirectory is created beneath
it, if it does not already have one.  This can repeated to any reasonable
depth: 

  REMOTE MKDIR a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p/q/r/s/t/u/v/w/z/y/z  

5.3.1.2. Removing Directories

When attempting to execute a REMOTE RMDIR, the server can remove only a single
directory, not an entire sequence or tree.  The system service that is called
to remove the directory generally requires not only that the server process
has write delete access, but also that the directory contain no files.

In the future, a REMOTE RMDIR /RECURSIVE command (and the accompanying
protocol) might be added.  For now, use the equivalent REMOTE HOST command(s),
if any.

5.4. Syntax for Remote Filenames with Embedded Spaces

C-Kermit and K95, when in server mode, assume that any spaces in the file
specification in an incoming GET command are filename separators.  Thus if
the client gives a command like:

  get {oofa.txt oofa.bin}

or, equivalently:

  mget oofa.txt oofa.bin

the server tries to send the two files, oofa.txt and oofa.bin.  But what if
you want the server to send you a file named, say:

  D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL

How does the server know this is supposed to be one file and not seven?
In this case, you need to the send file name to the server enclosed in either
curly braces:

  {D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL}

or ASCII doublequotes:

  "D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL"

The method for doing this depends on your client.  If your client is C-Kermit
6.1, any recent version of Kermit 95, or MS-DOS Kermit 3.16, then you have
to enclose the name in braces just so the client can parse it, so to send
braces or doublequotes to the server, you must put them inside the first,
outside pair of braces.  And you also need to double the backslashes to
prevent them from being interpreted:

  get {{D:\\HP OfficeJet 500\\Images\\My Pretty Picture Dot PCL}}
  get {"D:\\HP OfficeJet 500\\Images\\My Pretty Picture Dot PCL"}

To get around the requirement to double backslashes in literal filenames,
of course you can also use:

  set command quoting off
  get {{D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL}}
  get {"D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL"}
  set command quoting on

If you are giving a "kermit" command to the UNIX shell, you have to observe
the shell's quoting rules, something like this:

  kermit -ig "{D:\HP OfficeJet 500\Images\My Pretty Picture Dot PCL}"

Here, the quotes go on the outside so UNIX will pass the entire filename,
spaces, braces, and all, as a single argument to Kermit, and the backslashes
are not doubled because (a) the UNIX shell ignores them since they are in a
quoted string, and (b) Kermit ignores them since the interactive command parser
is not activated in this case.

(6) INTERNATIONAL CHARACTER SETS

6.1. The HP-Roman8 Character Set

The HP-Roman8 character set is supported in C-Kermit 6.0 but was omitted from
Table VII-4 due to lack of space.  See Appendix III below.

6.2. Greek Character Sets

Greek character sets were added in 6.1:

  SET FILE CHARACTER-SET { CP869, ELOT927, GREEK-ISO }
  SET TRANSFER CHARACTER-SET { GREEK-ISO }

GREEK-ISO is ISO 8859-7, which the same as ELOT 928.

The new Greek character sets are listed in Appendix III.	

(7) SCRIPT PROGRAMMING

(Also see Section 2.9, Scripting Local Programs.)

7.0. Bug Fixes

The following script programming bugs were fixed in C-Kermit 6.1:

 . IF EXIST and IF DIRECTORY were fixed to properly strip braces from around
   their arguments, so "if directory {C:\Program Files}", etc, would work as
   expected.  However, this means that if the file or directory name is
   actually enclosed in braces, the braces must be doubled.

 . The READ command did not fail if the READ file wasn't open; now it does.

 . The READ command refused to read the last or only line of a file if it did
   not end with a proper line terminator; now it does.

 . The END command, when given from within a SWITCH statement, did not exit
   from the current macro or command file; instead it just terminated the
   SWITCH.

7.1. INPUT Command Details

The description of the INPUT command on page 422 fails to mention the
following two points about the timeout (which apply to C-Kermit 6.0 and later):

 1. "INPUT -1 text" (or "INPUT \%x text", where \%x is any variable whose 
    value is -1 or less) means "wait forever".  This form of the INPUT command
    fails only if it is interrupted, since it will never time out.

 2. INPUT 0 performs a nonblocking read of material that has already arrived
    but has not yet been read, and succeeds immediately if the target string
    is found, or fails immediately if it is not found.

The same points apply to MINPUT.

The following new INPUT controls were added in version 6.1:

SET INPUT AUTODOWNLOAD { ON, OFF }
  Explained in section 7.7.

SET INPUT CANCELLATION { ON, OFF }
  This governs whether an INPUT command can be canceled by "pressing any key"
  on the keyboard.  Normally it can be, in which case the INPUT command fails
  immediately and \v(instatus) is set to 2, indicating interruption.  SET INPUT
  CANCELLATION OFF disables keyboard cancellations; thus if the search text is
  not encountered, the INPUT command will run for its entire timeout interval.
  SET INPUT CANCELLATION OFF does not disable interruption by Ctrl-C, however;
  every command needs an emergency exit.  (If you really want to disable
  interruption by Ctrl-C, use SET COMMAND INTERRUPTION OFF.)

Also see Section 7.2 for any new variables related to INPUT.

7.2. New or Improved Built-In Variables

\v(filename)
\v(filenumber)
  These are described in section 4.2.

\v(filespec), as of 6.1, contains fully qualified filenames rather than
  (usually) relative ones.

\v(editor)     - Pathname of preferred text editor
\v(editopts)   - Command-line options for editor
\v(editfile)   - File most recently edited

\v(browser)    - Pathname of preferred Web browser 
\v(browsopts)  - Command-line options for Web browser
\v(browsurl)   - URL most recently given to Web browser

\v(errno)      - In UNIX, the current value of the C runtime errno variable.
                 In VMS, the error code returned by the system or library
                 call that most recently failed (success codes are not saved).
                 Not available in other operating systems.

\v(errstring)  - The UNIX or VMS system error message that corresponds to
                 \v(errno).  Not available in other OS's.
                 Also see \ferrstring().

\v(exitstatus) - The exit status C-Kermit would return if it exited now.

\v(pexitstat) -  The exit status of the inferior process most recently invoked
                 by C-Kermit (by RUN, !, REDIRECT, SEND /COMMAND, etc).  In
                 VMS, this code can be given to \ferrstring() to get the
                 corresponding error message (in UNIX, program/command return
                 codes are not the same as system error codes).  Not available
                 in operating systems other than UNIX and VMS.  See section
                 4.2.5 for details.

\v(intime)     - The number of milliseconds (thousandths of seconds) it took
                 for the most recent INPUT command to find its match, or -1
                 if no INPUT command has been given yet.  If the INPUT command
                 timed out, the value is approximately equal to 1000 times the 
                 INPUT timeout.  If INPUT failed for some other reason, the
                 value is undefined (\v(instatus) gives INPUT completion
                 status).  If your version of C-Kermit is built without
                 high-precision floating-point timers, this number will always
                 be a multiple of 1000.

\v(pid)       -  UNIX, VMS, and K95 only.  C-Kermit's primary process ID,
                 numeric, decimal.  If you want to show it in hex, use
                 \fn2hex(\v(pid)).  If you want to show it in octal, use
                 \fn2octal(\v(pid)).

\v(printer)    - Current printer name or SET PRINTER value.

\v(p_ctl)      - Control prefix char
\v(p_8bit)     - 8-bit prefix char (if parity not none)
\v(p_rpt)      - Repeat prefix char (if repeat compression enabled)

\v(herald)     - Kermit's version herald
\v(test)       - Kermit's test version, if any, or 0 if this is not a test 
                 version.  Typical values for test versions are "Alpha.03"
                 or "Beta.14".

\v(sendlist)   - The number of entries in the SEND-LIST, 0 if none.  Note:
                 entries do not necessarily correspond to files, since an
                 entry might contain wildcards.  Also note that the value does
                 not go back to 0 after the files in the list are sent.  To
                 reset this variable, use CLEAR SEND-LIST.  The purpose of
                 this variable is to determine if a SEND command, when given
                 without any filenames, will be legal.  Example:
                   xif \v(sendlist) { send } else { send oofa.txt }

\v(trigger)    - If the most recent CONNECT session was terminated
                 automatically by a trigger, this variable contains the
                 trigger value.

\v(xferstat)   - Status of most recent file 
		  -1: No transfer yet
		   0: Succeeded
		   1: Failed

\v(xfermsg)    - If the most recent file transfer failed, this is the reason.
                 If it succeeded, \v(xfermsg) is an empty string.

\v(name)       - The name with which the Kermit program was invoked, e.g.
                 "kermit", "wermit", "k95", "k2", etc (see section 9.1).

\v(osname)     - Name of operating system on computer where C-Kermit is
                 running, obtained at runtime (from uname or equivalent).

\v(osversion)  - Version of operating system on computer where C-Kermit is
                 running, obtained at runtime (from uname or equivalent).

\v(osrelease)  - Release of operating system on computer where C-Kermit is
                 running, obtained at runtime (from uname or equivalent).

\v(model)      - The specific hardware model of the computer where C-Kermit
                 is running, if known.

Note the distinction between \v(osname)-\v(osversion) and \v(platform); the
latter refers to the platform for which and/or upon which C-Kermit was built,
as opposed to the one on which it is actually running.  Also note that each
operating system can, and probably will, interpret and fill in the os*
variables differently, or not at all.

The SHOW VARIABLES command now accepts a variable name, prefix, or pattern:

  show variables         Shows all variables.
  show variables t       Shows all variables that start with "t".
  show variables *ver*   Shows all variables whose names contain "ver".
  show variables *ver    Ditto (an implied "*" is appended).

7.3. New or Improved Built-In Functions

\ferrstring(n)
  Returns the system error message associated with the (numeric) error code n.
  UNIX and VMS only.  Use in conjunction with \v(errno) or \v(pexitstat).  See
  section 4.2.5 for a usage example.  Note: This function doesn't work in
  Windows because there is not a consistent error-code-to-message mapping;
  error code "x" means something completely different depending on whether it
  comes from the C runtime library, Winsock, a Windows-32 API, TAPI, etc,

\ffiles(), \fnextfile()
  It is no longer necessary to copy the file list to an array before use,
  as shown on p.398 of "Using C-Kermit" 2nd Edition.  \ffiles() and friends
  now make their own safe copies of the file list.  Thus constructions like
  the following are now possible:

    for \%i 1 \ffiles(*.txt) 1 { send \fnextfile() }

  The same is true for the new function \frfiles(), \fdirectories(), and
  \frdirectories(), described in section 4.11.3.

  But note that each reference to \fnextfile() still gets you the next file.
  So "if newer \fnextfile() foo.txt send \fnextfile()" compares one file's
  age with that of foo.txt, and then sends an entirely different file.  If
  you're going to refer to the same file more than once, assign it to a
  variable:  asg \%f \fnextfile(), if newer \%f foo.txt send \%f (note:
  assign, *not* define).

\fcommand()
\frawcommand()
  These are described in Section 4.2.8.3.

\fstripx(string,char)
  Returns the part of the string up to the rightmost occurrence, if any, of
  the given character.  The default character is period (.)  Examples:
    \fstripx(foo/bar,/)                 = "foo"
    \fstripx(foo/bar/baz,/)             = "foo/bar"
    \fstripx(autoexec.bat,.)            = "autoexec"
    \fstripx(autoexec.bat)              = "autoexec"
    \fstripx(fstripx(foo/bar/baz,/),/)  = "foo"

\flop(string,character)
  Returns the portion of the string starting after the first occurrence of
  the given character.  The default character is period (.)  Examples:
    \flop(foo/bar,/)                    = "bar"
    \flop(foo/bar/baz,/)                = "bar/baz"
    \flop(autoexec.bat,.)               = "bat"

\fstripn(string,n)
  Returns the string with n characters removed from the end.  Example:
  \fstripn(12345678,3)                  = "12345"

For more discussion of these functions, see section 4.2.3.

\fdirname(f)
  Given a file specification f, this function returns the complete pathname
  of directory the file is in.

\frandom(n)
  Returns a random number between 0 and n-1.

\fn2hex(n)
  Returns the hexadecimal (base 16) representation of the number n.  This is
  different from \fhexify(s), which treats its argument as a string rather
  than a number.  Note: the result is always left-padded with 0's to make its
  length even.
  Examples:
  \n2hex(0)   = "00"                    \fhexify(0)   = "30"
  \n2hex(255) = "ff"                    \fhexify(255) = "323535"
  \n2hex(256) = "0100"                  \fhexify(256) = "323536"

\fn2octal(n)
  Returns the octal (base 8) representation of the number n.  Examples:
  \n2octal(0) = "0"
  \n2oct(255) = "377"
  \n2oct(256) = "400"

\fword(s1,n,s2,s3)
  Extracts word number n from string s1.  By default, a "word" is any sequence 
  of ASCII letters or digits; n is 1-based.  If n is omitted, "1" is used.
  Examples:

    \fword(one two three)    = "one"
    \fword(one two three,1)  = "one"
    \fword(one two three,2)  = "two"
    \fword(one two three,3)  = "three"
  
  and:

    \fword(\v(dialresult),2) = "31200"

  is "31200" if \v(dialresult) is (e.g.) "CONNECT 31200/ARQ/V32/LAPM/V42BIS".

  If you include s2, this replaces the default break set.  For example,
  suppose you have a string \%a whose value is:

    $150.00 $300.00 $39.95

  and you want each dollar amount to be a word; use:

    \fword(\%a,\%n,{ })

  This returns dollar amount number \%n, e.g. "$300.00" for \%n = 2.  "{ }"
  denotes a space (you must enclose it in braces, otherwise it is squeezed
  out).  Note that ASCII control characters are always included in the break
  set; you don't have to specify them.

  The optional s3 argument lists characters that normally would be considered
  separators that you want included in words.  So the dollars-and-cents
  example could also be handled this way:

    \fword(\%a,\%n,,$.)

  in other words, use the default separator list, but remove "$" and "."
  from it so they will be considered part of a word.

\fsplit(s1,&a,s2,s3)
  This is like \fword(), except instead of extracting and returning a
  particular word from string s1, it assigns all its words to the array
  whose identifying letter, a-z, is given after the "&" in the second
  argument, with the first word going into element 1, the second into element
  2, and so on.  The rules regarding break and include lists (s2 and s3) are
  exactly the same as for \fword().  \fsplit() returns the number of words
  that were assigned, which is either the number of words in the string, or
  the dimension of the array, whichever is less.  If the array is not
  declared, \fsplit() returns 0.  Example:

     declare \&w[20]
     ...
     read \%s               ; \%s is "This is a sentence with seven words."
     ...
     echo "\fsplit(\%s,&w)" ; This would print "7".
     echo "\&w[7]"          ; This would print "words".     

  If the line contained fields that were delimited by colon (:), you would use
  \fsplit(\%s,&w,:).  If the fields were delimited by comma, then you would
  use \fsplit(\%s,&w,{,}); in this case the literal comma must be enclosed in
  braces to distinguish it from the comma that separates function arguments.

\fdimension(&a)
  Returns the dimension declared for the array whose identifying letter, a-z,
  or special character "_" or "@", is given after the "&" in the argument.  If
  the array is not declared, 0 is returned.  Note that when used with the
  macro argument vector array, \&_[], the value of this function is one less
  than \v(argc), and when used with the C-Kermit command-line argument vector
  array, \&@[], it is equal to the \v(args) variable.  Examples:
    echo \fdimension(&a) ; not declared
    0
    declare \&a[12]      ; now it's declared
    echo \fdim(&a)
    12

Also see Section 7.8 on built-in help for functions.

7.4. New IF Commands

IF AVAILABLE <feature> <command>
  Executes the <command> if the given <feature> is available.  Presently used
  only in Kerberized Kermit versions to see if Kerberos 4 or 5 connections are
  available.  Type "if available ?" to see which features may be tested.

IF <= n1 n2 <command>
  Executes the <command> if n1 and n2 are both numbers or variables containing
  numbers and the value of n1 is less than or equal to the value of n2.  This
  is equivalent to "if not > n1 n2".

IF >= n1 n2 <command>
  Executes the <command> if n1 and n2 are both numbers or variables containing
  numbers and the value of n1 is greater than or equal to the value of n2.
  Equivalent to "if not < n1 n2".

IF MATCH <string> <pattern> <command>
  Executes the <command> if the <string> matches the <pattern>.  The pattern
  may contain * to match any sequence of 0 or more characters, or ? to match
  any single character.  When giving this command at the prompt, any ?
  characters must be prefixed by \ to override the normal ?-help feature.

IF OPEN { DEBUG-LOG, SESSION-LOG, TRANSACTION-LOG, ... } <command>
  Executes the <command> if the given file is open, fails if it is not open.
  Type IF OPEN ? for a complete list of files that can be checked (all the
  files that can be opened with the OPEN or LOG commands).

IF FLAG <command>
  This tests a user-settable condition, which can mean anything you like.
  SET FLAG ON causes subsequent IF FLAG commands to succeed; SET FLAG OFF
  causes them to fail.  One way to use it would be for debugging your
  scripts; precede any debugging statements with IF FLAG.  Then SET FLAG on
  to debug your script, SET FLAG OFF to run it without debugging.

7.5. Using More than Ten Macro Arguments

The \v(argc) variable now gives the actual number of arguments, even if the
number is greater than 9:

  C-Kermit> define xx echo \v(argc)
  C-Kermit> xx a b c d e f g h i j k l m n o p q r s t u v w x y z
  27

Remember that \v(argc) includes the name of the macro itself, so it is always
at least 1, and is always 1 greater than the actual number of arguments.  As
in versions 6.0 and earlier, only the first 9 arguments are assigned to the
variables \%1..\%9.

The \&_[] array, discussed on page 353 of "Using C-Kermit", 2nd ed, now holds
all the arguments, up to some implementation-dependent limit (64 or greater),
rather than only the first 9.  To illustrate: the following macro tells the
number of arguments it was called with and then prints them:

  define show_all_args {
      local \%i
      echo \&_[0] - Number of arguments: \feval(\v(argc)-1)
      for \%i 1 \v(argc)-1 1 { echo \flpad(\%i,3). "\&_[\%i]" }
  }

Note that \&_[0], like \%0, contains the name of the macro.

The new \%* variable, when used within a macro, is replaced by the text that
followed the macro name in the macro invocation.  If no arguments are given,
\%* is replaced by the empty string.  Examples:

  C-Kermit> define xx echo [\%*]
  C-Kermit> define \%a oofa
  C-Kermit> xx
  []
  C-Kermit> xx \%a
  [oofa]
  C-Kermit> xx a
  [a]
  C-Kermit> xx a b
  [a b]
  C-Kermit> xx a b c
  [a b c]
  C-Kermit> xx a b c d e f g h i j k l m n o p q r s t u v w x y z
  [a b c d e f g h i j k l m n o p q r s t u v w x y z]

7.6. Clarification of Function Call Syntax

Braces are used in function calls to indicate grouping.  For example:

  \fsubstring(abcd,2,2) = "bc"

But suppose "abcd" needed to contain a comma:

  \fsubstring(ab,cd,2,2)

This would cause an error, since "cd" appears to be the second argument, when
really you want the first "2" to be the second argument.  Braces to the rescue:

  \fsubstring({ab,cd},2,2) = "b,"

Similarly, leading and trailing spaces are stripped from each argument, so:

  \fsubstring( abcd ,2,2) = "bc"

but braces preserve them:

  \fsubstring({ abcd },2,2) = "ab"

Given these special uses for braces, there is no way to pass literal braces to
the function itself.  For example:

  \fsubstring(ab{cd,2,2)

causes an error.

So if you need a function to include braces, define a variable containing the
string that has braces.  Example:

  define \%a ab{cd
  \fsubstring(\%a,2,2) = "b{"

If the string is to start with a leading brace and end with a closing brace,
then double braces must appear around the string (which itself is enclosed in
braces):

  define \%a {{{foo}}}
  \fsubstring(\%a) = "{foo}"

This also works for any other kind of string:

  define \%a {{ab{cd}}
  echo \fsubstring(\%a) = "ab{cd"

7.7. Autodownload during INPUT Command Execution

As of 6.1 / 1.1.12, C-Kermit can be told to look for incoming Kermit
(or Zmodem) packets during execution of an INPUT command.  By default (for
consistency with earlier releases), this is not done.  You can enable this
feature with:

  SET INPUT AUTODOWNLOAD ON

(and disable it again with OFF.)

One possible use for this feature is as a server mode with a time limit:

  INPUT 3600 secret-string-to-end-the-INPUT-command

In this example, any GET, SEND, or REMOTE commands received within one hour
(3600 seconds) of when the INPUT command was issued will be executed.  Here's
another example, in which we want to stay open until 11:30pm, or until
interrupted by seven consecutive Ctrl-C (\3) characters:

  INPUT 23:30:00 \3\3\3\3\3\3\3

The INPUT AUTODOWNLOAD setting is displayed by SHOW SCRIPTS or SHOW INPUT.

7.8. Built-in Help for Functions.

Beginning in C-Kermit 6.1, you may obtain a description of the calling
conventions and return values of any built-in function, such as
\fsubstring(), with the new HELP FUNCTION command; give the function's
name without the leading "\f", e.g. "help func substring".  You can use ?,
completion, and abbreviation in the normal manner.

7.9. Arrays

7.9.1. Array Initializers

Beginning in C-Kermit 6.1, you may initialize an array -- in whole or in part
-- in its declaration:

  DECLARE <array-name>[<size>] [ = ] [ <value1> [ <value2> [ ... ] ] ]

Initializers are (a) optional, (b) start with element 1, (c) can only be given
up to the size of the array, (d) must be enclosed in braces if they contain
spaces, (e) are stored literally and not evaluated by the DECLARE command.
Thus the assignments made here are the same as made by the DEFINE command.
Example:

  DECLARE \&a[16] = alpha beta {gamma delta}

declares the array \&a with 16 elements, initializing \&a[1] to "alpha",
\&a[2] to "beta", and \&a[3] to "gamma delta".  The remaining elements are
empty.  Extra elements are discarded and ignored.
                 
The equal sign (=) is optional, but is recommended for clarity.  If you need
to initialize element 1 to a literal equal sign, use two of them, separated by
a space, as in this example:

  DECLARE \&a[16] = = + - * /

7.9.2. Turning a String into an Array of Words 

The \fsplit(s1,&a,s2,s3) function assigns the words of string s1 to successive
elements of the array whose identifying letter, a-z, is given after the "&" in
the second argument, using break and include characters given in s2 and s3.
See Section 7.3 for details.

7.9.3. Automatic Arrays

In a command file or macro, you can now have local (automatic) arrays.
Just give the name followed by empty subscript brackets (no spaces inside
the brackets please):

  LOCAL \%a \&a[] oofa
  declare \&a[32] = value1 value2 value3 ...

This declares the scalar variable \%a, the array \&a[], and the macro name
"oofa" to be local, and then declares the new local copy of \&a[] with 32
elements, perhaps assigning some initial values.  When C-Kermit exits from the
command file or macro containing these command, the previous \&a[] array is
restored.  This can be repeated to any level.  Thus it is now safe to write
scripts or macros containing arrays without danger of interfering with global
arrays of the same name.

7.10. Assignment Operators

Programmers accustomed to languages such as C or Fortran might find Kermit's
method of assigning values to variables unnatural or awkward.  Beginning in
C-Kermit 6.1, you can use the following alternative notation:

 .name = value    is equivalent to   DEFINE name value
 .name := value   is equivalent to   ASSIGN name value
 .name ::= value  is equivalent to   EVALUATE value then assign result to name

When the command begins with a period (.), this indicates an assignment.
The name can be a macro name, a \%{digit,letter} variable, or an array
element.  There can be space(s) between "." and the name.  Examples:

  .\%a = This is a string  ; Same as "define \%a This is a string"
  echo \%a
  This is a string

  .xxx = \%a               ; Same as "define xxx \%a"
  echo \m(xxx)
  \%a

  .xxx := \%a              ; Same as "assign xxx \%a"
  echo \m(xxx)
  This is a string

  declare \&a[2]           ; Use with arrays...
  define \%i 2
  .\&a[1] = first
  .\&a[\%i] = second

The following sequence illustrates the differences among three levels of
evaluation:

  .\%x = 2          ; Define a variable to have a numeric value
  .\%y = (3 + \%x)  ; Define another variable as an arithmetic expression

  .xxx = 4 * \%y    ; "=" simply copies the right-hand side.
  echo \m(xxx)
  4 * \%y

  .xxx := 4 * \%y   ; ":=" evaluates the variables first, then copies.
  echo \m(xxx)
  4 * (3 + 2)

  .xxx ::= 4 * \%y  ; "::=" evaluates the expression, then copies.
  echo \m(xxx)
  20

7.11. New OUTPUT Command Options

SET OUTPUT SPECIAL-ESCAPES { ON, OFF }
  This command lets you tell C-Kermit whether to process \N, \L, and \B
  specially in an OUTPUT command, as distinct from other \-sequences (such
  as \%a, \13, \v(time), etc).  Normally the special escapes are handled.
  Use SET OUTPUT SPECIAL-ESCAPES OFF to disable them.
 
Disabling special escapes is necessary in situations when you need to transmit
lines of data and you have no control over what is in the lines.  For example,
a file oofa.txt that contains:

  This is a file
  It has \%a variables in it
  And it has \B in it.
  And it has \L in it.
  And it has \N in it.
  And this is the last line.

can be sent like this:

  local line
  open read oofa.txt
  while success {
      read line
      if fail break
      ; Add filtering or processing commands here...
      output \m(line)\13
  }

7.12. Function and Variable Diagnostics

SET FUNCTION DIAGNOSTICS { ON, OFF }
  when ON, allows built-in functions to return diagnostic messages when
  improperly referenced, instead of an empty string.  FUNCTION DIAGNOSTICS are
  ON by default.  When OFF, improperly referenced functions continue to return
  an empty string.  This command also affects built-in variables; in this case,
  an error message is returned only if the variable does not exist.

For variables, the only message is:

  <ERROR:NO_SUCH_VARIABLE:\v(name)>

where "name" is the name of the nonexistent variable.

For functions, the diagnostic message is:

  <ERROR:message:\fname()>

where "message" is replaced by a message, and "name" is replaced by the
function name, e.g. <ERROR:ARG_NOT_NUMERIC:\fmod()>.  Messages include:

  ARG_BAD_VARIABLE    An argument contains a malformed \%x variable.
  ARG_BAD_ARRAY       An argument contains a malformed array reference.
  ARG_EVAL_FAILURE    An argument could not be evaluated (internal error).
  ARG_NOT_ARRAY       An argument references an array that is not declared.
  ARG_NOT_NUMERIC     An argument that must be numeric is not numeric.
  ARG_NOT_VARIABLE    An argument that must be a variable is not a variable.
  ARG_OUT_OF_RANGE    An argument's value is too big or too small.
  ARG_TOO_LONG        An argument's value is too long.
  DIVIDE_BY_ZERO      Execution of the function would cause division by zero.
  LOOKUP_FAILURE      Error looking up function (shouldn't happen).
  MALLOC_FAILURE      Failure to allocate needed memory (shouldn't happen).
  NAME_AMBIGUOUS      The function is not uniquely identified.
  MISSING_ARG         A required argument is missing.
  NO_SUCH_FUNCTION    An argument references a function that is not defined.
  NO_SUCH_MACRO       An argument references a macro that is not defined.
  RESULT_TOO_LONG     The result of a function is too long.
  UNKNOWN_FUNCTION    Internal error locating function (shouldn't happen).

Examples:
  
  echo "\fmod()"
  "<ERROR:MISSING_ARG:\fmod()>"
  echo "\fmod(3,x)"
  "<ERROR:ARG_NOT_NUMERIC:\fmod()>"
  echo "\fmod(3,4-2*2)"
  "<ERROR:DIVIDE_BY_ZERO:\fmod()>"

The handling of function and variable errors is controlled by:

SET FUNCTION ERROR { ON, OFF }
  Tells whether invalid function calls or variable references should cause
  command errors.  FUNCTION ERROR is OFF by default.  When ON, and an error is
  diagnosed in a built-in function or variable, the command that includes the
  function call or variable reference fails.  The failing command can be
  handled in the normal way with IF FAILURE / IF SUCCESS, SET TAKE ERROR, or
  SET MACRO ERROR.

When FUNCTION ERROR is ON, the error message is printed just like other
error messages.  When FUNCTION ERROR is OFF, the error message is returned
(enclosed in <point_brackets>) as the value of the function or variable.

When FUNCTION DIAGNOSTICS is OFF, there is no error message.

SHOW SCRIPTS displays the current FUNCTION DIAGNOSTICS and ERROR settings.

(8) USING OTHER FILE TRANSFER PROTOCOLS

Alternative protocols can now be selected using switches.  Switches are
described in section 1.5; the use of protocol-selection switches is described
in section 4.7.1.  Example:

  send /binary /protocol:zmodem x.tar.gz

Note that file transfer recovery works only with Kermit and Zmodem protocols.
With ZMODEM, recovery can only be initiated by the sender.

(9) COMMAND-LINE OPTIONS

9.1. Command Line Personalities

Beginning in version 6.1, if the C-Kermit binary is renamed to "telnet"
(or TELNET.EXE, telnet.pr, etc, depending on the platform), it accepts the
Telnet command line:

  telnet [ host [ port ] ]

When installed in this manner, C-Kermit always reads its initialization file.
If no host (and therefore no port) is given, C-Kermit starts in interactive
prompting mode.  If a host is given as the first command-line argument,
C-Kermit makes a connection to it.  The host argument can be an IP host name
or address, or the name of a TCP/IP entry in your C-Kermit network directory.

If a port is given, it is used.  If a port is not given, then if the hostname
was found in your network directory and port was also listed there, then that
port is used.  Otherwise port 23 (the Telnet port) is used.

When C-Kermit is called "telnet" and it is invoked with a hostname on the
command line, it exits automatically when the connection is closed.  While
the connection is open, however, you may escape back and forth as many times
as you like, transfer files, etc.

Additional personalities (e.g. rlogin) might be added in the future.

The new variable \v(name) indicates the name with which C-Kermit was invoked
("kermit", "wermit", "k95", "telnet", etc).

9.2. Built-in Help for Command Line Options

"kermit -h", given from the system prompt, lists as many command-line options
as will fit on a standard 24x80 screen.  For more comprehensive help, use the
interactive HELP OPTIONS command that was added in C-Kermit 6.1:

HELP OPTIONS
  Explains how command-line options work, their syntax, etc.

HELP OPTIONS ALL
  Lists all command-line options and gives brief help about each one.

HELP OPTION x
  Gives brief help about option "x".

9.3. New Command-Line Options

Command-line options added since C-Kermit 6.0 are:

-G: GET (like -g), but send the incoming file to standard output.  Example:
    "kermit -G oofa.txt | lpr" retrieves a file from your local computer
    (providing it is running a Kermit program that supports the autodownload
    feature and has it enabled) and prints it.

-O: equivalent to -x (start up in server mode), but exits after the first
    client command has been executed (mnemonic: O = Only One).

-L: Recursive, when used in combination with -s (mnemonic: L = Levels).
    In UNIX or other environments where the shell expands wildcards itself,
    the -s argument, if it contains wildcards, must be quoted to prevent
    this, e.g.:

      kermit -L -s "*.c"

    In UNIX only, "kermit -L -s ." means to send the current directory tree.
    See sections 4.10-4.11 about recursive file transfer.

-V: Equivalent to SET FILE PATTERNS OFF (Section 4.3) and SET TRANSFER MODE
    MANUAL.  In other words, take the FILE TYPE setting literally.  For
    example, "kermit -VT oofa.bin" means send the file in Text mode, no matter
    what its name is and no matter whether a kindred spirit is recognized at
    the other end of the connection.

-0: (digit zero) means "be 100% transparent in CONNECT mode".  This is
    equivalent to the following series of commands: SET PARITY NONE, SET
    COMMAND BYTESIZE 8, SET TERMINAL BYTESIZE 8, SET FLOW NONE, SET
    TERM ESCAPE DISABLED, SET TERM CHAR TRANSPARENT, SET TERM AUTODOWNLOAD
    OFF, SET TERM APC OFF.

III. APPENDICES

III.1.  Character Set Tables

III.1.1. The Hewlett Packard Roman8 Character Set

dec col/row oct hex  description
160  10/00  240  A0  (Undefined)
161  10/01  241  A1  A grave
162  10/02  242  A2  A circumflex
163  10/03  243  A3  E grave
164  10/04  244  A4  E circumflex
165  10/05  245  A5  E diaeresis
166  10/06  246  A6  I circumflex
167  10/07  247  A7  I diaeresis
168  10/08  250  A8  Acute accent
169  10/09  251  A9  Grave accent
170  10/10  252  AA  Circumflex accent
171  10/11  253  AB  Diaeresis
172  10/12  254  AC  Tilde accent
173  10/13  255  AD  U grave
174  10/14  256  AE  U circumflex
175  10/15  257  AF  Lira symbol
176  11/00  260  B0  Top bar (macron)
177  11/01  261  B1  Y acute
178  11/02  262  B2  y acute
179  11/03  263  B3  Degree Sign
180  11/04  264  B4  C cedilla
181  11/05  265  B5  c cedilla
182  11/06  266  B6  N tilde
183  11/07  267  B7  n tilde
184  11/08  270  B8  Inverted exclamation mark
185  11/09  271  B9  Inverted question mark
186  11/10  272  BA  Currency symbol
187  11/11  273  BB  Pound sterling symbol
188  11/12  274  BC  Yen symbol
189  11/13  275  BD  Paragraph
190  11/14  276  BE  Florin (Guilder) symbol
191  11/15  277  BF  Cent symbol
192  12/00  300  C0  a circumflex
193  12/01  301  C1  e circumflex
194  12/02  302  C2  o circumflex
195  12/03  303  C3  u circumflex
196  12/04  304  C4  a acute
197  12/05  305  C5  e acute
198  12/06  306  C6  o acute
199  12/07  307  C7  u acute
200  12/08  310  C8  a grave
201  12/09  311  C9  e grave
202  12/10  312  CA  o grave
203  12/11  313  CB  u grave
204  12/12  314  CC  a diaeresis
205  12/13  315  CD  e diaeresis
206  12/14  316  CE  o diaeresis
207  12/15  317  CF  u diaeresis
208  13/00  320  D0  A ring
209  13/01  321  D1  i circumflex
210  13/02  322  D2  O with stroke
211  13/03  323  D3  AE digraph
212  13/04  324  D4  a ring
213  13/05  325  D5  i acute
214  13/06  326  D6  o with stroke
215  13/07  327  D7  ae digraph
216  13/08  330  D8  A diaeresis
217  13/09  331  D9  i grave
218  13/10  332  DA  O diaeresis
219  13/11  333  DB  U diaeresis
220  13/12  334  DC  E acute
221  13/13  335  DD  i diaeresis
222  13/14  336  DE  German sharp s
223  13/15  337  DF  O circumflex
224  14/00  340  E0  A acute
225  14/01  341  E1  A tilde
226  14/02  342  E2  a tilde
227  14/03  343  E3  Icelandic Eth
228  14/04  344  E4  Icelandic eth
229  14/05  345  E5  I acute
230  14/06  346  E6  I grave
231  14/07  347  E7  O acute
232  14/08  350  E8  O grave
233  14/09  351  E9  O tilde
234  14/10  352  EA  o tilde
235  14/11  353  EB  S caron
236  14/12  354  EC  s caron
237  14/13  355  ED  U acute
238  14/14  356  EE  Y diaeresis
239  14/15  357  EF  y diaeresis
240  15/00  360  F0  Icelandic Thorn
241  15/01  361  F1  Icelandic thorn
242  15/02  362  F2  Middle dot
243  15/03  363  F3  Greek mu
244  15/04  364  F4  Pilcrow sign
245  15/05  365  F5  Fraction 3/4
246  15/06  366  F6  Long dash, horizontal bar
247  15/07  367  F7  Fraction 1/4
248  15/08  370  F8  Fraction 1/2
249  15/09  371  F9  Feminine ordinal
250  15/10  372  FA  Masculine ordinal
251  15/11  373  FB  Left guillemot
252  15/12  374  FC  Solid box
253  15/13  375  FD  Right guillemot
254  15/14  376  FE  Plus or minus sign
255  15/15  377  FF  (Undefined)

III.1.2. Greek Character Sets

III.1.2.1. The ISO 8859-7 Latin / Greek Alphabet = ELOT 928

dec col/row oct hex  description
160  10/00  240  A0  No-break space
161  10/01  241  A1  Left single quotation mark
162  10/02  242  A2  right single quotation mark
163  10/03  243  A3  Pound sign
164  10/04  244  A4  (UNUSED)
165  10/05  245  A5  (UNUSED)
166  10/06  246  A6  Broken bar
167  10/07  247  A7  Paragraph sign
168  10/08  250  A8  Diaeresis (Dialytika)
169  10/09  251  A9  Copyright sign
170  10/10  252  AA  (UNUSED)
171  10/11  253  AB  Left angle quotation
172  10/12  254  AC  Not sign
173  10/13  255  AD  Soft hyphen
174  10/14  256  AE  (UNUSED)
175  10/15  257  AF  Horizontal bar (Parenthetiki pavla)
176  11/00  260  B0  Degree sign
177  11/01  261  B1  Plus-minus sign
178  11/02  262  B2  Superscript two
179  11/03  263  B3  Superscript three
180  11/04  264  B4  Accent (tonos)
181  11/05  265  B5  Diaeresis and accent (Dialytika and Tonos)
182  11/06  266  B6  Alpha with accent
183  11/07  267  B7  Middle dot (Ano Teleia)
184  11/08  270  B8  Epsilon with accent
185  11/09  271  B9  Eta with accent
186  11/10  272  BA  Iota with accent
187  11/11  273  BB  Right angle quotation
188  11/12  274  BC  Omicron with accent
189  11/13  275  BD  One half
190  11/14  276  BE  Upsilon with accent
191  11/15  277  BF  Omega with accent
192  12/00  300  C0  iota with diaeresis and accent
193  12/01  301  C1  Alpha
194  12/02  302  C2  Beta
195  12/03  303  C3  Gamma
196  12/04  304  C4  Delta
197  12/05  305  C5  Epsilon
198  12/06  306  C6  Zeta
199  12/07  307  C7  Eta
200  12/08  310  C8  Theta
201  12/09  311  C9  Iota
202  12/10  312  CA  Kappa
203  12/11  313  CB  Lamda
204  12/12  314  CC  Mu
205  12/13  315  CD  Nu
206  12/14  316  CE  Ksi
207  12/15  317  CF  Omicron
208  13/00  320  D0  Pi
209  13/01  321  D1  Rho
210  13/02  322  D2  (UNUSED)
211  13/03  323  D3  Sigma
212  13/04  324  D4  Tau
213  13/05  325  D5  Upsilon
214  13/06  326  D6  Phi
215  13/07  327  D7  Khi
216  13/08  330  D8  Psi
217  13/09  331  D9  Omega
218  13/10  332  DA  Iota with diaeresis
219  13/11  333  DB  Upsilon with diaeresis
220  13/12  334  DC  alpha with accent
221  13/13  335  DD  epsilon with accent
222  13/14  336  DE  eta with accent
223  13/15  337  DF  iota with accent
224  14/00  340  E0  upsilon with diaeresis and accent
225  14/01  341  E1  alpha
226  14/02  342  E2  beta
227  14/03  343  E3  gamma
228  14/04  344  E4  delta
229  14/05  345  E5  epsilon
230  14/06  346  E6  zeta
231  14/07  347  E7  eta
232  14/08  350  E8  theta
233  14/09  351  E9  iota
234  14/10  352  EA  kappa
235  14/11  353  EB  lamda
236  14/12  354  EC  mu
237  14/13  355  ED  nu
238  14/14  356  EE  ksi
239  14/15  357  EF  omicron
240  15/00  360  F0  pi
241  15/01  361  F1  rho
242  15/02  362  F2  terminal sigma
243  15/03  363  F3  sigma
244  15/04  364  F4  tau
245  15/05  365  F5  upsilon
246  15/06  366  F6  phi
247  15/07  367  F7  khi
248  15/08  370  F8  psi
249  15/09  371  F9  omega
250  15/10  372  FA  iota with diaeresis
251  15/11  373  FB  upsilon with diaeresis
252  15/12  374  FC  omicron with diaeresis
253  15/13  375  FD  upsilon with accent
254  15/14  376  FE  omega with accent
255  15/15  377  FF  (UNUSED)

III.1.2.2. The ELOT 927 Character Set

dec col/row oct hex  description
 32  02/00   40  20  SPACE
 33  02/01   41  21  EXCLAMATION MARK
 34  02/02   42  22  QUOTATION MARK
 35  02/03   43  23  NUMBER SIGN
 36  02/04   44  24  DOLLAR SIGN
 37  02/05   45  25  PERCENT SIGN
 38  02/06   46  26  AMPERSAND
 39  02/07   47  27  APOSTROPHE
 40  02/08   50  28  LEFT PARENTHESIS
 41  02/09   51  29  RIGHT PARENTHESIS
 42  02/10   52  2A  ASTERISK
 43  02/11   53  2B  PLUS SIGN
 44  02/12   54  2C  COMMA
 45  02/13   55  2D  HYPHEN, MINUS SIGN
 46  02/14   56  2E  PERIOD, FULL STOP
 47  02/15   57  2F  SOLIDUS, SLASH
 48  03/00   60  30  DIGIT ZERO
 49  03/01   61  31  DIGIT ONE
 50  03/02   62  32  DIGIT TWO
 51  03/03   63  33  DIGIT THREE
 52  03/04   64  34  DIGIT FOUR
 53  03/05   65  35  DIGIT FIVE
 54  03/06   66  36  DIGIT SIX
 55  03/07   67  37  DIGIT SEVEN
 56  03/08   70  38  DIGIT EIGHT
 57  03/09   71  39  DIGIT NINE
 58  03/10   72  3A  COLON
 59  03/11   73  3B  SEMICOLON
 60  03/12   74  3C  LESS-THAN SIGN, LEFT ANGLE BRACKET
 61  03/13   75  3D  EQUALS SIGN
 62  03/14   76  3E  GREATER-THAN SIGN, RIGHT ANGLE BRACKET
 63  03/15   77  3F  QUESTION MARK
 64  04/00  100  40  COMMERCIAL AT SIGN
 65  04/01  101  41  CAPITAL LETTER A
 66  04/02  102  42  CAPITAL LETTER B
 67  04/03  103  43  CAPITAL LETTER C
 68  04/04  104  44  CAPITAL LETTER D
 69  04/05  105  45  CAPITAL LETTER E
 70  04/06  106  46  CAPITAL LETTER F
 71  04/07  107  47  CAPITAL LETTER G
 72  04/08  110  48  CAPITAL LETTER H
 73  04/09  111  49  CAPITAL LETTER I
 74  04/10  112  4A  CAPITAL LETTER J
 75  04/11  113  4B  CAPITAL LETTER K
 76  04/12  114  4C  CAPITAL LETTER L
 77  04/13  115  4D  CAPITAL LETTER M
 78  04/14  116  4E  CAPITAL LETTER N
 79  04/15  117  4F  CAPITAL LETTER O
 80  05/00  120  50  CAPITAL LETTER P
 81  05/01  121  51  CAPITAL LETTER Q
 82  05/02  122  52  CAPITAL LETTER R
 83  05/03  123  53  CAPITAL LETTER S
 84  05/04  124  54  CAPITAL LETTER T
 85  05/05  125  55  CAPITAL LETTER U
 86  05/06  126  56  CAPITAL LETTER V
 87  05/07  127  57  CAPITAL LETTER W
 88  05/08  130  58  CAPITAL LETTER X
 89  05/09  131  59  CAPITAL LETTER Y
 90  05/10  132  5A  CAPITAL LETTER Z
 91  05/11  133  5B  LEFT SQUARE BRACKET
 92  05/12  134  5C  REVERSE SOLIDUS, BACKSLASH
 93  05/13  135  5D  RIGHT SQUARE BRACKET
 94  05/14  136  5E  CIRCUMFLEX ACCENT
 95  05/15  137  5F  UNDERSCORE
 96  06/00  140  60  ACCENT GRAVE
 97  06/01  141  61  GREEK LETTER ALPHA
 98  06/02  142  62  GREEK LETTER BETA
 99  06/03  143  63  GREEK LETTER GAMMA
100  06/04  144  64  GREEK LETTER DELTA
101  06/05  145  65  GREEK LETTER EPSILON
102  06/06  146  66  GREEK LETTER ZETA
103  06/07  147  67  GREEK LETTER ETA
104  06/08  150  68  GREEK LETTER THETA
105  06/09  151  69  GREEK LETTER IOTA
106  06/10  152  6A  GREEK LETTER KAPPA
107  06/11  153  6B  GREEK LETTER LAMDA
108  06/12  154  6C  GREEK LETTER MU
109  06/13  155  6D  GREEK LETTER NU
110  06/14  156  6E  GREEK LETTER KSI
111  06/15  157  6F  GREEK LETTER OMICRON
112  07/00  160  70  GREEK LETTER PI
113  07/01  161  71  GREEK LETTER RHO
114  07/02  162  72  GREEK LETTER SIGMA
115  07/03  163  73  GREEK LETTER TAU
116  07/04  164  74  GREEK LETTER UPSILON
117  07/05  165  75  GREEK LETTER FI
118  07/06  166  76  GREEK LETTER XI
119  07/07  167  77  GREEK LETTER PSI
120  07/08  170  78  GREEK LETTER OMEGA
121  07/09  171  79  SPACE
122  07/10  172  7A  SPACE
123  07/11  173  7B  LEFT CURLY BRACKET, LEFT BRACE
124  07/12  174  7C  VERTICAL LINE, VERTICAL BAR
125  07/13  175  7D  RIGHT CURLY BRACKET, RIGHT BRACE
126  07/14  176  7E  TILDE
127  07/15  177  7F  RUBOUT, DELETE

III.1.2.3. PC Code Page 869

(to be filled in...)

III.2. Updated Country Codes

Date: Mon, 7 Apr 1997 23:23:49 EDT
From: Dave Leibold <dleibold@else.net>
Newsgroups: comp.dcom.telecom
Subject: Ex-USSR Country Codes Profile
Organization: TELECOM Digest

Ex-USSR Country Codes Profile
4 April 1997

Below is a summary of the country codes that have formed in the wake
of the USSR dissolution, along with some updated findings and reports. 
Additional or corrected information on any of these nations would be 
welcome (c/o dleibold@else.net).

* Kyrgyz Republic country code 996 will take effect, at least in
  Canada, effective 1 May 1997, according to CRTC Telecom Order 97-464,
  based on Stentor Tariff Notice 433. There is no indication whether
  there will be a permissive dialing period involved or for how long
  such a permissive operation would remain.

* Country code 992 was reported as a recent assignment for Tajikistan,
  which will be moving from country code 7 at some unknown time.

* Uzbekistan has its own country code assignment, but I have no
  information if this is in service yet or what implementation dates
  have been set.

* Kazakstan does not have a known separate country code assignment
  at present. It remains in country code 7 for the time being.

* Russia seems destined to keep country code 7.

* Recent news reports speak of some agreements forming between Russia and
Belarus. While there is no outright reunification yet, there is expected
to be much closer ties between the two nations. Whether this will lead to
a reunification of telephone codes remains to be seen. 

In the table, "Effective" means the date at which the country code
began service (which could vary according to the nation). "Mandatory"
means the date at which the country code 7 is invalid for calls to
that nation. There are a number of question marks since exact
dates have not been collected in all cases.

CC  Nation            Effective     Mandatory    Notes

370 Lithuania         1993?         ???          Announced Jan 1993
371 Latvia            1993?         ???
372 Estonia           1 Feb 1993?   March 1993?
373 Moldova           1993?         ???          Announced Jan 1993
374 Armenia           1 May 1995    1 July 1995  Announced Jan 1995 (ITU)
375 Belarus           16 Apr 1995   1997?
380 Ukraine           16 Apr 1995   Oct 1995?
7   Kazakstan         (no known changes)
7   Russia            (presumably not changing)
992 Tajikistan        ???           ???          Announced 1996-7?
993 Turkmenistan      3 Jan 1997    3 Apr 1997   Canada as of 29 Nov 1996
994 Azerbaijan        Sept 1994?    ???          Announced 1992
995 Georgia           1994?         ???          ref: Telecom Digest Oct 1994
996 Kyrgyz Republic   1 May 1997    ???          ref: Stentor Canada/CRTC
998 Uzbekistan        ???           ???          Announced 1996? (ITU)

Details courtesy Toby Nixon, ITU, Stentor (Canada), CRTC (Canada),
TELECOM Digest (including information collected for the country code
listings).

  
IV. ERRATA & CORRIGENDA

The following errors in "Using C-Kermit", Second Edition, first printing,
have been noted.

First, some missing acknowledgements: JE Jones of Microware for help with
OS-9, Nigel Roles for his help with Plan 9, Lucas Hart for help with VMS and
Digital UNIX, Igor Kovalenko for his help with QNX.  And later, to Susan
Kleinmann for her help with Debian Linux packaging; Patrick Volkerding for his
help with Slackware Linux packaging; Jim Knoble for his help with Red Hat
Linux packaging; and to hundreds of others for sending individual C-Kermit
binaries for varied and diverse platforms.  And special thanks to James Spath
for both binaries and for reporting many of the typos noted below:

PAGE    REMARKS
COVER   "COS" is a misprint.  There is no COS.  Pretend it says "SCO" or "VOS".
        (This is fixed in the second printing.)
 xxi    Second line: Fred Smith's affiliation should be Computrition.
 83     Change "commands other" to "commands as other" (1st paragraph)
 87     Change "The the" to "The" (2nd paragraph)
 92     "set modem-type user-defined supra" should be "set modem type ..."
 95     Change "VI" to "vi" (1st paragraph)
 96     Change "it it" to "it is" (1st paragraph)
 97     Change "advantage a literal" to "advantage of a literal" (2nd
        paragraph)
102     The call-waiting example would be better as SET DIAL PREFIX *70W
        (rather than "*70,") because the former will not cause an incorrect
        call to be placed with pulse dialing.
123     Third paragraph from bottom: "..otherwise if a your local username.."
        should be "..otherwise your local username..".
160     Delete the "it" between "and" and "to" (2nd paragraph)
185     In "When TRANSFER DISPLAY is OFF, C-Kermit skips the display...",
        "OFF" should be "NONE".
187     The last paragraph says the "A command" is ignored, should be "S".
194     Change "it known" to "it is known" (4th paragraph).
268     Last paragraph: "effect" should be "affect".
279     9th line.  The decimal value of ST is 156, not 155.
295     In the stepping stones, skip ahead to Chapter 17 on p. 327.
298     Table 16-2, Portuguese entry.  Column 4/00 should show section sign,
        not acute accent.
316     Other languages written in the Hebrew alphabet include Karaim (a Turkic
        language spoken in Lithuania and Poland), Judeo-Kurdish, and Judeo-
        Georgian. 
332     UNDEFINE definition, change "This just" to "This is just".
344     It might be necessary to set the modem's pulse generation rate when
        sending numeric pages; most Hayes compatible modems use the S11 
        register for this.
350     Delete "is" from between "It" and "ceases" (4th paragraph)
351     Top - both occurrences of "print \%a" should be "echo \%a".
364     \v(input) and \v(query) out of alphabetical order.
382-383 It should be stated that the loop control variable must be of the \%a 
        type, or else an array element; macro names can not be used for this.
387     Change "You can list" to "You can get a list" (5th paragraph)
393     \Fverify() description.  The 3rd sentence could be stated more clearly
        as "If all characters in string2 are also in string1, 0 is returned."
398     Copying \ffiles() results to an array before is not required as of
        C-Kermit 6.1 (see section 7.3).
409     READ example while loop should be:
        while success { echo \m(line), read line }
409     "WRITE file" should be "WRITE keyword" (you can't put a filename there)
        (The same applies to WRITE-LINE / WRITELN).
414     \Funhexify() missing from Table 18-3.
425     MINPUT definition, change 2nd "text2" to "text3".
436     Several lines are missing from the UNIXLOGIN macro listing.
        After the "xif fail" block, insert:

	  out \%1\13                    ; Send username, carriage return
	  inp 5 Password:               ; Wait 5 sec for this prompt
	  if fail end 1 No password prompt
	  pause                         ; Wait a sec
	  out \%2\13                    ; Send password

440     Change "set terminal byteszie" to "set terminal bytesize" 
448     Franchise script: "access line" should be "access \m(line)".
453     "the the" (last paragraph) should be "the".
454     EOT (last paragraph) is End of Transmission, not End of Text.
457     _DEFINE definition: "name constructed" should be "name is constructed".
457     "macro for and" (last paragraph) should be "macro and".
459     Should explain that \v(user) is a legal abbreviation of \v(userid).
480     Figure II-2 is backwards; the least-significant bit is transmitted
        first, then up to the highest, and the parity bit last.
534     The VMS Appendix section on Odd Record Lengths no longer applies;
        C-Kermit 6.1 handles odd record lengths as well as even ones.
559     Table VIII-3, Portuguese entry.  Column 4/00 should show section sign,
        not acute accent.
560-563 HP-Roman8 missing from Table VII-4; there wasn't room to squeeze it in.
        It is listed in section II(6).
565     "d stroke" in Table VII-5 has the wrong appearance; the stem should
        be upright.  The letter shown in the table is actually a lowercase
        Icelandic eth, which has a curved stem.
601-604 BeBox, BeOS, Plan 9, and probably others not listed in trademarks.
604     The words "SCRIBE TEXT FORMATTER" appear at the end of the last
        sentence of the first paragraph of the Colophon.  They should have
        been in the Index.
Index:  Missing entries: SET { SEND, RECEIVE } PATHNAMES, Call waiting, ...
	\F()            Page 605, add also 413-414
	\Fbreak         389
	\Fcapitalize    390
	\Fchecksum      414
	\Fcrc16         414
	\Fexecute       414
	\Fhexify        390
	\Fltrim         391
        \Frepeat        392
	\Fspawn         392
	\Ftod2sec       399
	\v() built_in   Page 606, add also 361-364
	\v(_line)       354, 361
	\v(apcactive)   361
	\v(charset)     362
	\v(cpu)         362
	\v(crc16)       357, 362
	\v(d$xxx)       add page 362
	\v(dialnumber)  362
	\v(dialresult)  362
	\v(errno)       362
	\v(errstring)   362
	\v(exedir)      362
	\v(inidir)      363
	\v(ipaddress)   363
	\v(keyboard)    363
	\v(macro)       363
	\v(minput)      363
	\v(m_xxx)       94, 363
	\v(password)    364
	\v(query)       364
	\v(prompt)      364
	\v(speed)       356, 364
	\v(startup)     364
	\v(status)      364
	\v(sysid)       364
	\v(system)      364
	\v(fsize)       at lower half page 606 should read \v(tfsize)
	\v(xversion)    364
        BEEP Command     40

Figure II-5 on page 493.  The pin assignments of the Mini Din-8 connector
are not described anywhere.  As noted in the text, these tend to vary from
vendor to vendor.  One common arrangement is:

  1. HSKout (Handshake out -- definition depends on software)
  2. HSKin  (Handshake in or external clock)
  3. TxD-
  4. Not used
  5. RxD-
  6. TxD+
  7. Not used
  8. RxD+

Note the "balanced pairs" for Receive Data (RxD) and Transmit Data (TxD), and
the utter lack of modem signals.  These connectors follow the RS-423 standard,
rather than RS-232.  In some arrangements, Pin 1 is used for DTR and Pin 2 for
CD; in others Pin 1 is RTS and Pin 2 is CTS.

Please send reports of other errors to the authors, as well as suggestions for
improvements, additional index entries, and any other comments:

  kermit@columbia.edu

APPENDIX V. ADDITIONAL COPYRIGHT NOTICES

The following copyrights cover some of the source code used in the development
of C-Kermit, Kermit 95, or Kermit 95 support libraries.

/*****************************************************************************/
/*                                                                           */
/*              Copyright (c) 1995 by Oy Online Solutions Ltd.               */
/*                                                                           */
/*   Distribution of this source code is strictly forbbidden. Use of this    */
/*   source code is granted to the University of Columbia C-Kermit project   */
/*   to be distributed in binary format only. Please familiarize yourself    */
/*   with the accompanying LICENSE.P file.                                   */
/*                                                                           */
/*****************************************************************************/

used for Xmodem, Ymodem, and Zmodem protocol in Kermit 95 (p95.dll, p2.dll)

-----

Copyright (c) 1997 Stanford University

The use of this software for revenue-generating purposes may require a
license from the owners of the underlying intellectual property.
Specifically, the SRP-3 protocol may not be used for revenue-generating
purposes without a license.

Within that constraint, permission to use, copy, modify, and distribute
this software and its documentation for any purpose is hereby granted
without fee, provided that the above copyright notices and this permission
notice appear in all copies of the software and related documentation.

THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND,
EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY
WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

IN NO EVENT SHALL STANFORD BE LIABLE FOR ANY SPECIAL, INCIDENTAL,
INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF
THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Used for Secure Remote Password (TM) protocol (SRP) in C-Kermit, 
Kermit 95 (k95.exe, k2.exe, k95crypt.dll, k2crypt.dll)

-----

Copyright 1990 by the Massachusetts Institute of Technology.
All Rights Reserved.

Export of this software from the United States of America may
  require a specific license from the United States Government.
  It is the responsibility of any person or organization contemplating
  export to obtain such a license before exporting.

WITHIN THAT CONSTRAINT, permission to use, copy, modify, and
distribute this software and its documentation for any purpose and
without fee is hereby granted, provided that the above copyright
notice appear in all copies and that both that copyright notice and
this permission notice appear in supporting documentation, and that
the name of M.I.T. not be used in advertising or publicity pertaining
to distribution of the software without specific, written prior
permission.  M.I.T. makes no representations about the suitability of
this software for any purpose.  It is provided "as is" without express
or implied warranty.


Used for Telnet Authentication Option, Telnet Encryption Option,
and Kerberos (TM) authentication in C-Kermit, Kermit 95 (k95.exe, k2.exe, 
k95crypt.dll, k2crypt.dll)

-----

Copyright (c) 1991, 1993
The Regents of the University of California.  All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement:
This product includes software developed by the University of
California, Berkeley and its contributors.
4. Neither the name of the University nor the names of its contributors
   may be used to endorse or promote products derived from this software
   without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Used for Telnet Authentication Option, Telnet Encryption Option,
and Kerberos (TM) authentication in C-Kermit, Kermit 95 (k95.exe, k2.exe, 
k95crypt.dll, k2crypt.dll)

-----

Copyright (C) 1995-1997 Eric Young (eay@cryptsoft.com)
All rights reserved.

This package is an DES implementation written by Eric Young
(eay@cryptsoft.com).  The implementation was written so as to conform with
MIT's libdes.

This library is free for commercial and non-commercial use as long as
the following conditions are aheared to.  The following conditions
apply to all code found in this distribution.

Copyright remains Eric Young's, and as such any Copyright notices in
the code are not to be removed.
If this package is used in a product, Eric Young should be given attribution
as the author of that the SSL library.  This can be in the form of a textual
message at program startup or in documentation (online or textual) provided
with the package.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the copyright
   notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
   notice, this list of conditions and the following disclaimer in the
   documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software
   must display the following acknowledgement:
   This product includes software developed by Eric Young (eay@cryptsoft.com)

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

The license and distribution terms for any publically available version or
derivative of this code cannot be changed.  i.e. this code cannot simply be
copied and put under another distrubution license
[including the GNU Public License.]

The reason behind this being stated in this direct manner is past
experience in code simply being copied and the attribution removed
from it and then being distributed as part of other packages. This
implementation was a non-trivial and unpaid effort.

Used DES encryption in Kermit 95 (k95crypt.dll, k2crypt.dll)

----

 * This is version 1.1 of CryptoLib
 *
 * The authors of this software are Jack Lacy, Don Mitchell and Matt Blaze
 *              Copyright (c) 1991, 1992, 1993, 1994, 1995 by AT&T.
 * Permission to use, copy, and modify this software without fee
 * is hereby granted, provided that this entire notice is included in
 * all copies of any software which is or includes a copy or
 * modification of this software and in all copies of the supporting
 * documentation for such software.
 *
 * NOTE:
 * Some of the algorithms in cryptolib may be covered by patents.
 * It is the responsibility of the user to ensure that any required
 * licenses are obtained.
 *
 *
 * SOME PARTS OF CRYPTOLIB MAY BE RESTRICTED UNDER UNITED STATES EXPORT
 * REGULATIONS.
 *
 *
 * THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED
 * WARRANTY.  IN PARTICULAR, NEITHER THE AUTHORS NOR AT&T MAKE ANY
 * REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY
 * OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

Used for Big Number library in Kermit 95 (k95crypt.dll, k2crypt.dll).  

------------------------------
END OF CKERMIT2.UPD