If you are reading the HTML version of this file
with a GUI Web browser, the features added since C-Kermit 8.0.201 are
shown in red if your browser and monitor permit.
Features that were new to versions 8.0.200 and 201 are in black.

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

Incompatible Changes

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

echo {this is a string}

would print:

this is a string

whereas:

echo "this is a string"

printed:

"this is a string"

In C-Kermit 8.0, both print:

this is a string

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

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

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

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

Other incompatibilities:

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

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

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

An obscure path through the code could cause the Unix version
of C-Kermit to dump core during its startup sequence. This happened
to only one person, but now it's fixed.

When C-Kermit 8.0 is in Kermit server mode and the client says
"get blah", where blah (on the server) is a symlink rather than a real
file, the server unreasonably refused to send the linked-to file.

When C-Kermit is an FTP client and says "get foo/bar" (i.e. a filename
that includes one or more path segments), it failed to accept the
incoming file (this happened only with GET, not MGET).

Array references should be case insensitive but only lowercase array
letters were accepted.

SHOW VARIABLES dumped core on \v(sexpression)
and \v(svalue).

Spurious refusals of remote directory listings if the remote server's
date was set in the past.

In AIX, and maybe elsewhere too, Kermit's COPY command always failed with
"Source and destination are the same file" when the destination file didn't
exist.

The VMS version of C-Kermit did not work in Batch or when SPAWN'd.
To compound the problem, it also pretty much ignored the -B and -z
command-line options, whose purpose is to work around such problems.

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

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

SSHtext

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

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

SET SSH COMMANDtext

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

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

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

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

to make the connection.

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

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

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

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

Example:

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

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

-e none

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

-l username

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

-T

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

-s ... kermit

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

hostname

The IP host name or address of the desired host.

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

-oClearAllForwardings yes

-oForwardAgent no

-oForwardX11 no

-oFallbackToRsh no

These ensure that a secure connection is used and that the connection
used for file transfer is not also used for forwarding other things
that might be specified in the ssh_config file.

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

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

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

Allowing an HTTP connection to be open at the same time as a regular SET
LINE or SET HOST connection, and also at the same time as an FTP connection
(Section 3);

Upgrading the HTTP protocol level from 1.0 to 1.1, thus allowing for
persistent connections, in which a series of commands can be sent on the same
connection, rather than only one as in HTTP 1.0 (and C-Kermit 7.0);

Providing for "one-shot" URL-driven HTTP operations such as GET or PUT.

Providing a distinct HTTP command-line personality.

Persistent HTTP connections are managed with the following commands:

HTTP[ switches ]OPEN[ security-options ] host-or-url [ port ]

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

HTTP CLOSE

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

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

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

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

http open http://www.columbia.edu/

Equivalent to httpopenwww.columbia.edu
or httpopenwww.columbia.eduhttp.

http open https://olga.secret@www1.xyzcorp.com/

Equivalent to
http/user:olga/pass:secretopenwww1.xyzcorp.com https.

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

Firewalls can be negotiated through proxies with the following commands:

SET TCP HTTP-PROXY[ host[:port] ]

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

HTTP[ switches ]CONNECThost[:port]

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

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

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

/USER:name

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

/PASSWORD:text

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

/AGENT:user-agent

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

/ARRAY:array-designator

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

/TOSCREEN

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

/HEADER:header-item(s)

Used for specifying any optional headers to be sent with HTTP requests.

/HEADER:tag:value

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

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

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

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

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

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

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

HTTP[ switches ]GETremote-filename [ local-filename ]

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

HTTP[ switches ]GETurl [ local-filename ]

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

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

HTTP[ switches ]HEADremote-filename-or-url
[ local-filename ]

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

HTTP[ switches ]INDEXremote-directory-or-url
[ local-filename ]

Asks the server to send a listing of the files in the given server
directory. This command is not supported by most Web servers. Even when it
is supported, there is no standard format for the listing.

Sends data to a process running on the remote host; the result is usually
an HTML file but could be anything.
The data to be
posted must be read from a local file (the source-file). If a result
file is specified, Kermit stores the server's response in it.

Uploads a local file to the server. Only the name of a single file can be
given; wildcards (and group transfers) are not supported by HTTP protocol. If
no remote filename is given, the file is sent with the same name as the local
file, but with any pathname stripped.

HTTP[ switches ]DELETEremote-file-or-url
[ local-result-file ]

Asks the server to delete the specified single file. If a result file is
specified, it will contain any response data returned by the server.

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

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

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

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

A secure client (a version of C-Kermit or Kermit 95 with SSL/TLS security
built in). Type "check ssl" at the Kermit prompt to make sure you have it.

A secure server to connect to.

The CA Root Certificate used to authenticate the server to the client.
(see Section 15 of the security reference
for an introduction to certificates).

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

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

Anonymous cipher suite:

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

X.509 certificate on the server:

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

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

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

X.509 client certificate:

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

Kerberos 5:

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

An HTTP connection is made with the HTTP OPEN command:

HTTP[ switches ]OPEN[ {/SSL, /TLS} ] host [ port ]

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

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

SET AUTHENTICATION TLS CRL-DIRdirectory

Specifies a directory that contains certificate revocation files where
each file is named by the hash of the certificate that has been revoked.

SET AUTHENTICATION TLS CRL-FILEfilename

Specifies a file that contains a list of certificate revocations.

SET AUTHENTICATION TLS VERIFY-DIRdirectory

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

SET AUTHENTICATION TLS VERIFY-FILEfilename

Specifies a file that contains root CA certificates to be used for
verifying certificate chains.

SET AUTHENTICATION TLS VERIFY OFF

Tells Kermit not to require a certificate and accept any certificate
that is presented regardless of whether it is valid.

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

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

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

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

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

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

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

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

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

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

Character sets
can be translated as part of the transfer process even when the FTP server
does not support character-set translation, including to/from the new Internet
standard international character set, Unicode UTF-8. This
includes both the file's name and (for text files only) its contents.

The correct file type, "ascii" (i.e. text) or binary,
is chosen automatically for each file (explained in Section
4), and any mixture of text and binary files can be sent in a single
operation, even across platforms.

Update mode ("don't bother transferring files that didn't change since
last time") and recovery (resumption of an interrupted transfer from the
point of failure) are available in both directions.

When uploading files from UNIX to UNIX, the file's permissions can be
preserved if desired.

Recursive directory-tree PUTs are supported between any two platforms
that have tree-structured file systems. Recursive GETs are supported
between like platforms if the server cooperates
and between like or unlike platforms if the server supports
MLSD (Section 3.11).

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

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

kermit -9 hostname

or if a non-default FTP port is needed:

kermit -9 hostname:port

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

kermit -9 hostname -M olga

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

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

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

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

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

ftp [ options ] hostname [ port ]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

If the FTP personality is used,
the service must be "ftp". In all cases,
a hostname or address must be included. If a
user is included but no password, you are prompted for the password. If a
path (filename) is included:

If "@" is included without a user, Kermit
prompts for the username and password.

If no user
and no "@" are included, "anonymous" is used.

GET is assumed.

If no path (and no action options) are included, an interactive FTP
session is started, as in this example:

ftp ftp://kermit.columbia.edu

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

Here's an example that gets a listing of the Kermit directory at the
Kermit ftp site:

ftp ftp://kermit.columbia.edu/kermit/

This example gets the top-level READ.ME file from the same directory:

ftp ftp://kermit.columbia.edu/kermit/READ.ME

Here's the same example, but requesting a text-mode transfer:

ftp -T ftp://kermit.columbia.edu/kermit/READ.ME
This illustrates that you can mix command-line options and URLs if you desire.

Here's an example that logs in as a (fictitious) real user to get a file:

ftp ftp://olga@ftp.xyzcorp.com/resume.txt
The password is not included, so Kermit prompts for it.

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

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

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

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

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

An FTP session is established with the FTP OPEN command:

FTP[OPEN]
[ {/SSL, /TLS} ]
hostname [ switches ] [ port ]

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

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

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

The optional FTP OPEN switches are:

/ANONYMOUS

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

/NOLOGIN

Overrides SET FTP AUTOLOGIN ON for this connection only.

/USER:name

Uses the given username to log you in, thus avoiding the Name: prompt.

Overrides SET FTP AUTOLOGIN OFF for this connection only.

/PASSWORD:text

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

/ACCOUNT:text

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

/PASSIVE

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

/ACTIVE

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

/NOINIT

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

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

Examples:

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

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

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

FTP BYE

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

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

SET FTP ANONYMOUS-PASSWORDtext

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

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

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

FTP ACCOUNTtext

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

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

FTP RESET

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

FTP IDLE[ number ]

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

FTP STATUS[ filename ]

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

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

FTP SITEtext

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

FTP QUOTEtext

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

SHOW FTP

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

The simplist form of firewall traversal is the HTTP CONNECT command. The
CONNECT command was implemented to allow a public web server which usually
resides on the boundary between the public and private networks to forward
HTTP requests from clients on the private network to public web sites. In
order to allow secure web connections to be established, the CONNECT command
works by authenticating the client with a username/password and then
establishing a tunnel to the desired host.

Many web servers support the CONNECT command and it can be configured to allow
outgoing connections to authenticated user to any TCP/IP hostname/port
combination accessible to the web server. The limitations of HTTP CONNECT is
that it can only be used for outgoing connections for protocols that are
implemented using TCP/IP. Protocols such as Kerberos authentication that use
UDP/IP cannot be tunneled using HTTP CONNECT.

Kermit provides support for the use of HTTP CONNECT proxy services with the
command:

When a port is not specified the default port configured on the HTTP server is
used. This is frequently port 443. When a hostname is specified, it is
resolved using the DNS available to the web server.

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

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

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

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

SET FTP AUTHTYPE{AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS}

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

SET FTP AUTOAUTHENTICATION{ON, OFF}

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

SET FTP AUTOENCRYPTION{ON, OFF}

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

SET FTP AUTOLOGIN{ON, OFF}

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

SET FTP COMMAND-PROTECTION-LEVEL{CLEAR, CONFIDENTIAL, PRIVATE, SAFE}

Determines the level of protection applied to the command channel:

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

The default is PRIVATE.

SET FTP CREDENTIAL-FORWARDING{ON, OFF}

Tells whether end-user credentials are to be forwarded to the server if
supported by the authentication method (GSSAPI-KRB5 only). This is often
required to allow access to distributed file systems (e.g. AFS.)

SET FTP DATA-PROTECTION-LEVEL{CLEAR, CONFIDENTIAL, PRIVATE, SAFE}

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

SET FTP SRP CIPHERname

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

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

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

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

3.3.1. Logs, Messages, and Other Feedback

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

SET TRANSACTION-LOG{VERBOSE, FTP, BRIEF}

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

LOG TRANSACTIONSfilename

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

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

SET TRANSFER DISPLAY{FULLSCREEN, CRT, SERIAL,
BRIEF, NONE, OFF}

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

SET FTP DISPLAY{FULLSCREEN, CRT, SERIAL,
BRIEF, NONE, OFF}

Like SET TRANSFER DISPLAY, but applies only to FTP
connections, and does not affect Kermit- or other protocol file transfers.

SET QUIET{ON, OFF}

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

SET FTP PROGRESS-MESSAGES{ON, OFF}

Tells whether Kermit should print locally-generated feedback messages for
each non-file-transfer command. ON by default.

SET FTP VERBOSE-MODE{ON, OFF}

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

SET FTP DEBUG{ON, OFF}

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

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

3.3.2. Operational Preferences

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

SET FTP PASSIVE-MODE{ON, OFF}

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

SET FTP SEND-PORT-COMMANDS{ON, OFF}

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

SET FTP CHARACTER-SET-TRANSLATION{ON, OFF}

Whether to translate character sets when transferring files with FTP
(explained in Section 3.7). OFF by default.

SET FTP SERVER-CHARACTER-SETname

Tells Kermit the character set used by the FTP server, UTF-8 by default
(Section 3.7).

SET FTP SERVER-TIME-OFFSETdelta-time

Tells Kermit to apply the given delta
time to file timestamps provided by the server for its files; for
use when (for example) the server does not have its timezone set
correctly.

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

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

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

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

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

SET FTP COLLISION{...}

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

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

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

A remote computer when you have a connection to a Kermit server or IKSD.

A remote computer when you have a connection to an FTP server.

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

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

With no prefix in C-Kermit 8.0.200, it refers to the local computer
(CD, DIR, etc). In C-Kermit 8.0.201 and later, however, the "locus" switches
to automatically to the remote FTP server when you make an FTP connection (see
the SET LOCUS description Section 7); thus C-Kermit 8.0.201
acts almost exactly like a regular FTP client when it has an FTP connection,
yet still acts like itself on other kinds of connections.

With the REMOTE prefix, it is for a Kermit server (REMOTE CD,
REMOTE DIR).

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

FTP CD[ directory ]

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

FTP CDUP

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

FTP PWD

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

FTP MKDIRdirectory

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

FTP RMDIRdirectory

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

FTP DIRECTORY[ filespec ] [ redirectors ]

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

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

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

FTP MODTIMEfilename

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

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

FTP SIZEfilename

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

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

ftp chmod 664 oofa.txt

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

FTP UMASK[ number ]

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

FTP RENAMEfilename newname

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

FTP DELETE[ switches ] filespec [ filespec [ ... ] ]

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

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

FTP TYPE{TEXT, BINARY, TENEX}

Tells the FTP server to change its file-transfer type to the one given,
immediately. See SET FTP TYPE for details.

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

FTP PUT[ switches ] [ filespec [ as-name ] ]

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

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

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

FTP MPUT[ switches ] filespec [ filespec [ ... ] ]

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

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

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

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

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

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

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

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

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

/LARGER-THAN:number

/SMALLER-THAN:number

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

/TYPE:{TEXT,BINARY}

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

/[NO]DOTFILES

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

/NOBACKUPFILES

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

/NOFOLLOWLINKS

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

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

/RECURSIVE

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

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

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

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

/COMMAND

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

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

/LISTFILE:filename

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

Now the other switches:

/AS-NAME:text

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

/BINARY

/TEXT

/TENEX

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

/FILTER:command

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

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

ftp mput /server-rename:\v(filename).ok *

Appends ".ok" to each filename on the server when it's finished
uploading.

ftp mput /as-name:\v(filename).tmp /server-rename:\v(filename) *

This is the reverse of the previous example; it uses a temporary name
while uploading is in progress and reverts the file to its real name when
uploading is complete.

ftp mput /as-name:\v(filename) /server-rename:../final/\v(filename) *

Moves the file from the working directory to a final
directory when the upload is complete,
but in this case you have to know the pathname syntax of the server. If the
rename fails, the [M]PUT command fails according to the
FTP ERROR-ACTION selection.

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

/QUIET

Don't display file-transfer progress or statistics.

/SIMULATE

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

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

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

ftp put /update [ other-switches ] *

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

The remote filename is determined in the normal way, according to
the FTP FILENAMES
setting, /FILENAMES switch, or the as-name, if any.

Kermit sends an MDTM (modification time) command for the corresponding
remote filename to the server.

If the server does not understand the MDTM command, the file is sent.

If the server can't find a file with the given name, the file is sent.

If the local file's modification time is later than that of the remote
file, the file is sent.

Otherwise -- the remote file exists but its modification time is equal
to or earlier than that of the local file -- the file is skipped.

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

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

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

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

Notes:

Why is Coordinated Universal Time abbreviated UTC? From the
National Institute of Standards and Technology FAQ:
"In 1970 the Coordinated Universal Time system was devised by an
international advisory group of technical experts within the
International Telecommunication Union (ITU). The ITU felt it was
best to designate a single abbreviation for use in all languages in
order to minimize confusion. Since unanimous agreement could not be
achieved on using either the English word order, CUT, or the French
word order, TUC, the acronym UTC was chosen as a compromise."

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

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

The FTP server must support the SIZE command.

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

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

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

If it is not binary (determined by scanning) and the client and server
are not on like platforms, recovery is canceled (the entire file is sent).
Otherwise:

A SIZE command is sent for the file (using its remote name). If the
reply indicates the file was not found, or the SIZE command was not
understood, or any other kind of error, recovery is canceled. Otherwise:

A MDTM (modification time) command is sent for the file. If a valid
reply is received, and the modification time of the local file is later
than that of the remote file, recovery is canceled. Otherwise:

If the sizes of the two files are identical, the file is not sent.
Otherwise:

Kermit seeks to the recovery spot in the local file, tells the server
to APPEND the data which is about to arrive to the remote file, and then
sends the data starting at the recovery point.

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

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

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

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

If the original upload involved a translation from one single-byte
character set to another (e.g. Code Page 850 to Latin-1), recovery is
safe if you specify the same translations for the recovery. If you don't,
the resulting file will contain a mixture of character sets.

If the original upload involved a translation that changed the size
of the file (e.g. from an alphabetic Code Page or Latin Alphabet to
Unicode, or vice versa), recovery is NOT safe, even if you specify
the same translations.

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

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

If you want to get more than one file, you have to use MGET, not GET,
since the underlying FTP protocol is different in the two cases. Kermit
can't "autodetect" which one you mean, as it can with PUT and MPUT,
since it can't be expected to know the wildcard syntax of the remote
platform and/or FTP server (the same is true for all other FTP clients).
To complicate matters, FTP protocol now includes two
underlying mechanisms (NLST and MLSD) for accomplishing MGET operations
and, as explained in Section 3.11, the two behave
differently.

Automatic text-binary mode switching is not done by the server. It can
be done by the client (Kermit), but in this case it is not based on a file
scan (since there is no way for Kermit prescan a server file), but rather
on the filename, using C-Kermit 7.0
filename patterns.

Some options that are available with FTP PUT can not be used with FTP
[M]GET or don't work the same way:

/PERMISSIONS (FTP protocol has no mechanism for this)./[NOT-]BEFORE, /[NOT-]AFTER (because of the timezone problem)./RECOVER works only in binary mode.
/RECURSIVE has limited utility.

The commands for downloading are:

SET FILE DOWNLOAD-DIRECTORY[ directory ]

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

SET FTP GET-FILETYPE-SWITCHING{ON, OFF}

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

[FTP]GET[ switches ] filename [ as-name ]

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

[FTP]MGET[ switches ] filespec [ filespec [ filespec [ ... ] ] ]

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

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

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

X to interrupt the current file and go on to the next file.

Z (or Control-C) to cancel the current file and all
remaining files.

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

The location of the temporary file is chosen according the TMP or TEMP
environment variables. If neither of these variables is defined, you might
need to define it. In case there is not enough space on the indicated
disk or partition for the server's file list, you might need to either clean
up the temporary area, or redefine the environment variable to indicate a
different area that has sufficient space.

If you want to look at the list yourself, use SET FTP DEBUG ON. This
tells Kermit to (a) give you the full pathname of the temporary file
at the end of each MGET command, and (b) not to delete it, as it
normally does.

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

/BINARY

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

/TENEX

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

/RECOVER

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

/FILENAMES:{CONVERTED,LITERAL}

Overrides the FTP FILENAMES
(filename conversion) setting for this download only, forcing incoming
filenames to be either converted or taken literally.

/AS-NAME:text

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

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

/QUIET

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

/ERROR-ACTION:{QUIT,PROCEED}

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

The file selection switches are:

/EXCEPT:{pattern}or/EXCEPT:{{pattern}{pattern}{...}}

Exception list for MGET; skip downloading any file whose name matches
any of the given patterns (when using the second format, up to
64 patterns may be specified).
CLICK HERE for syntax details.

/SMALLER-THAN:number

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

/LARGER-THAN:number

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

/NOBACKUPFILES

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

/NODOTFILES

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

/LISTFILE:local-filename

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

/NAMELIST:local-filename

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

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

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

get somepath/somefile

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

get /recursive somepath/somefile

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

mget */data/*

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

mget /recursive */data/*

re-creates the server's directory structure locally.

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

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

Source-file disposition switches:

/DELETE

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

/SERVER-RENAME-TO:template

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

Destination-file disposition switches:

/TO-SCREEN

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

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

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

/RENAME-TO:template

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

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

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

If an as-name was given, the as-name is used. Otherwise:

If the client and server platforms are alike or
FTP FILENAMES is set to
LITERAL (or the /FILENAMES:LITERAL switch was given for this download),
the incoming filename is used literally. Otherwise:

The incoming filename is converted to a form that is friendly to the
local platform. For UNIX, for example, incoming filenames that are all
uppercase (as they might be from, say, VMS or an IBM mainframe) are
converted to lowercase.

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

SET FTP COLLISION{BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE}

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

FTP GET /COLLISION:{BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE}

Overrides the current FTP COLLISION action for this download only.

FTP GET /UPDATE

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

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

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

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

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

The transfer must be in BINARY mode. It can not be in text mode, even
if the FTP server is on the same kind of platform as Kermit, and even
if there is no character-set translation. The original download must also
have been in binary mode.

The FTP server must support the REST ("restart") directive. Unfortunately,
this is not a standard command; at this writing, it is described only in
an Internet Draft, not an RFC or Internet Standard, but nevertheless it is
found in several popular FTP servers, such as
ProFTPD.

Here's how download recovery works:

Kermit checks for conflicting switches, such as /UPDATE, /COMMAND, or
/FILTER. If /RECOVER is given with these switches an error occurs.

The prevailing transfer mode (SET FTP TYPE) must be BINARY. If it is not,
the /BINARY switch must have been included with the FTP [M]GET command.

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

A SIZE command is sent for the file (using its remote name). If the
reply indicates the file was not found, or the SIZE command was not
understood, or any other kind of error, recovery is canceled (i.e. the
entire file is downloaded).

If the sizes of the two files are identical, the file is not sent.
Otherwise:

Kermit sends the REST directive to the server, indicating the size of the
local file. If the server responds affirmatively, Kermit opens the local
file in append mode and appends the incoming data to it. Otherwise,
recovery is canceled and the entire file is downloaded.

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

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

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

SET FTP CHARACTER-SET-TRANSLATION{ON, OFF}

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

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

This is the regular Kermit (non-FTP-specific) command for identifying the
character set (to be) used in local text files and filenames.

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

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

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

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

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

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

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

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

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

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

/LOCAL-CHARACTER-SET:name

/SERVER-CHARACTER-SET:name

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

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

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

Examples:

Suppose you have a CP852 (East European) text file that you want to upload
and store in ISO Latin Alphabet 2 encoding:

ftp put /local-char:cp852 /server-char:latin2 magyar.txt

Suppose you always want your text files converted to Latin-2 when uploading
with FTP. Then put:

set ftp server-character-set latin2

in your Kermit customization file, and then you can omit the
/SERVER-CHARACTER-SET: switch from your FTP PUT commands:

ftp put /local-char:cp852 magyar.txt

Now suppose that all the text files on your PC are written in Hungarian,
but they have a variety of encodings, and you don't want to have to include the
/LOCAL-CHARACTER-SET: switch on every FTP PUT command, or (more to the point)
you want to be able to send a mixture of these files all at once. Put these
commands in your Kermit customization file:

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

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

Examples:

get /server-char:latin1 /local-char:cp850 Grüße.txt

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

Tells C-Kermit to translate the incoming files into Unicode UTF-8 for
storage.

Asks the server to send all ".txt" files in text mode.

mget /server:latin1 /local:utf8 *

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

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

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

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

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

SET GET-PUT-REMOTE{AUTO, KERMIT, FTP}

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

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

When GET-PUT-REMOTE is set to KERMIT, or to AUTO when there is no FTP
connection, the commands in the left-hand column access Kermit protocol,
and those right-hand column are required for FTP.

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

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

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

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

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

The security method negotiated for the current FTP session. The value
is "NULL" when no security is used. Other possibilities are GSSAPI,
KERBEROS_V4, SSL, TLS, and SRP. Also see
\v(authname),
\v(authstate), and
\v(authtype).
See
3.2. Making Secure FTP Connections.

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

FTP file transfers set the regular Kermit transfer status variables:

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

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

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

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

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

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

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

It can be stored in a file, and Kermit can be told to TAKE the file.

In UNIX, it can be a "kerbang" script and
therefore run directly from the shell prompt or as a cron job.

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

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

Make sure that SET TAKE ERROR and SET MACRO ERROR are both OFF. This
is the default, but in case you have set either one of these ON in your
script or initialization file, this makes the script halt on any kind of
error. Normally you would want to check each operation for success or
failure and take appropriate action.

On SSL and TLS connections, you may be asked whether it is OK to proceed
with a connection to server that presents a self-signed certificate. You
can use the SET AUTHENTICATION SSL (or TLS) VERIFY or SET AUTH SSL (or TLS)
CERTS-OK commands to avoid this prompt by not requesting a certificate from
the peer.

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

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

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

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

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

FTP{ENABLE, DISABLE}FEAT

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

500 'FEAT': command not understood

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

FTP ENABLE{MDTM, MLST, SIZE}

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

FTP DISABLE{MDTM, MLST,
SIZE}

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

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

FTP FEATURES

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

FTP OPTIONSdirective

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

FTP SIZEfilename

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

FTP MODTIMEfilename

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

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

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

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

NLST *.txt

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

foo.txt
bar.txt
baz.txt

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

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

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

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

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

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

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

For recursive downloads since there is no dependable way to download
directory trees with NLST.

But it is better to use NLST:

If you want only a couple short files out of a large directory. In this
case, NLST is the better choice since the server sends a list of only the
files you want, not a list of (say) a million files, which can make a big
difference on slow connections. For example, suppose your wildcard matches
three files of 1K each, but the million-file listing is 80MB long, and your
connection is through a modem. The overhead of using MLSD is practically
infinite.

If the server supports wildcarding features not known to the client, but
that can be used to achieve desirable effects otherwise unobtainable, such as
"[dir...]*.txt" in VMS or AOS/VS "except" clauses.

If you have been given a wildcard string by an FTP site administrator for
fetching a specific group of files out of a larger directory, e.g.
"mgetck[cuw]*.[cwh]makefile",
that is expected to work with any client (an FTP site administrator can't be
expected to know the wildcard syntax of every FTP client).

But when using MLSD there are complications:

MLSD wants either a blank argument (meaning the current directory) or
else the name of a specific directory. The client must not send it a
wildcard or a filename.

But if the user's command is "mget xxx", how does the client know whether
to send "xxx" in the MLSD directive? It might be the name of a directory
on on the server, in which case it should be sent, or it might be the
name of a file on the server (or a wildcard), in which case it must not
be sent. Since the client knows its own wildcard syntax, then in most
cases it would be right to send "MLSD" with no argument if xxx is wild,
and to send "MLSD xxx" if it is not.

But suppose the server's file system allows filename characters that
correspond with the client's wildcard syntax? For example:
"[abc]" could be either a valid VMS directory name or a wildcard
pattern used by the FTP client. What should the client do with "mget[abc]"? In this case there must be a way for the user to force
sending the MGET argument as the MLSD argument.

If "xxx" is a regular file in the server's current
directory, "mget xxx" works with NLST but not with MLSD.

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

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

The MGET command should produce the expected result in the common cases,
regardless of whether NLST or MLSD is used underneath.

For anomalous cases, the user needs a way to control whether the MGET
argument is sent to the server or kept for local use.

At the same time, the user might need a way to send a directory name to
the server, independent of any wildcard pattern.

The user needs a way to force NLST or MLSD for a given MGET command.

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

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

/NLST

Forces the client to send NLST. Example:

mget /nlst foo.*

/MLSD

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

mget /mlsd foo.*

/MATCH:pattern

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

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

For downloading all or most of the files in a directory, MLSD is better
because it eliminates the need to send SIZE and MDTM for each file. No
special actions are required in this case; Kermit uses MLSD automatically if
the server supports it (unless you have disabled it).

For a small number of files from a large directory, NLST is better because
it bypasses downloading of a potentially huge file list prior to the files
themselves. If you have a connection to a server that supports MLSD, use the
/NLST switch to force NLST:

mget /nlst t[1234].h

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

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

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

MGET /RECURSIVE

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

MGET /RECURSIVE *.txt

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

MGET /MLSD /RECURSIVE *.txt

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

MGET /RECURSIVE /MATCH:*.zip archives

Tells the server to send all ZIP files in the tree rooted at its
"archives" directory.

MGET /RECURSIVE /MATCH:* [abc]

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

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

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

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

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

User's Command

FTP Sends

Remarks

mget /nlst

NLST

Gets a list of all the files in the server's current and
downloads each file. The list includes names only, so Kermit also must send
SIZE and MDTM directives if size and timestamp information is required (this
is always true of NLST). Sending NLST without an argument is allowed by the
RFC959 NLST definition and by the Kermit FTP client, but might not work with
other clients, and also might not work with every server.

mget /nlst foo

NLST foo

If "foo" is a directory, this gets a list of all the files
from the server's "foo" directory and downloads each file; otherwise this
downloads the file named "foo" (if any) from the server's current directory.

mget /nlst *.txt

NLST *.txt

Gets a list of the files in the server's current directory
whose names match the pattern *.txt, and then downloads each file
from the list. Because we are using NLST, we send the filespec
(*.txt) to the server and the server interprets any wildcards.

mget /nlst foo/*.txt

NLST foo/*.txt

Gets a list of the files in the server's "foo" directory
whose names match the pattern *.txt, and then downloads each file
from the list (server interprets wildcards).

mget /nlst /match:*.txt

NLST

Gets a list of all the files in the server's current
directory and then downloads each one whose name matches the pattern
*.txt (client interprets wildcards).

mget /nlst /match:*.txt foo

NLST foo

Gets a list of all the files in the server's "foo"
directory and then downloads each one whose name matches the pattern
*.txt (client interprets wildcards).

mget /mlsd

MLSD

Gets a list of all the files from the server's current
directory and then downloads each one. The list might include size and
timestamp information, in which case Kermit does not need to send SIZE
and MDTM directives for each file (this is always true of MLSD).

mget /mlsd foo

MLSD foo

Gets a list of all the files from the server's "foo"
directory (where the string "foo" does not contain wildcards) and then
downloads each one. If "foo" is a regular file and not a directory, this
command is supposed to fail, but some servers have been observed that send
the file.

mget /mlsd *.txt

MLSD

Gets a list of all the files from the server's current
directory and then downloads only the ones whose names match the pattern
"*.txt". Because we are using MLSD and the MGET filespec is wild, we
do not send the filespec to the server, but treat it as though it had
been given in a /MATCH: switch and use it locally to match the names in the
list.

mget /mlsd foo/*.txt

MLSD

This one won't work because MLSD requires that the notions of
server directory and filename-matching pattern be separated. However, the
client, which can't be expected to know the server's file-system syntax, winds
up sending a request that the server will (or should) reject.

mget /mlsd /match:*.txt

MLSD

Gets a list of all the files from the server's current
directory and then downloads only the ones whose names match the pattern
"*.txt" (client interprets wildcards).

mget /mlsd /match:*.txt foo

MLSD foo

If "foo" is a directory on the server, this gets a list of
all the files from the server's "foo" directory and then downloads only the
ones whose names match the pattern "*.txt" (client interprets
wildcards). This leaves the server CD'd to the "foo" directory; there's no
way the client can restore the server's original directory because MLSD
doesn't give that information, and since the client can not be expected to
know the server's file-system syntax, it would not be safe to guess. If "foo"
is a regular file, MLSD fails.

mget /mlsd foo bar

MLSD

This one is problematic. You're supposed to be able to give
MGET a list a filespecs; in this case we name two directories. The client
must change the server's directory to "foo" to get the list of files, and then
the files themselves. But then it has no way to return to the server's
previous directory in order to do the same for "bar", as explained in the
previous example.

mget /mlsd /match:* [abc]

MLSD [abc]

Including a /MATCH: switch forces [abc] to be sent to
the server even though the client would normally think it was a wildcard and
hold it for local interpretation. In this example, [abc] might be
a VMS directory name.

mget /mlsd /match:* t*.h

MLSD t*.h

Contrary to the MLSD specification, some MLSD-capable FTP
servers do interpret wildcards. This form of
the MGET command can be used to force a wildcard to be sent to the server
for interpretation.

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

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

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

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

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

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

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

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

8-BIT TEXT

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

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

UTF8 TEXT

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

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

SET TRANSFER MODE{AUTOMATIC, MANUAL}

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

SET FILE SCAN{ON[ number ],OFF}

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

SET FILE DEFAULT 7BIT-CHARACTER-SETname

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

SET FILE DEFAULT 8BIT-CHARACTER-SETname

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

ASSOCIATE FILE-CHARACTER-SETfcs tcs

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

ASSOCIATE TRANSFER-CHARACTER-SETtcs fcs

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

SET FILE CHARACTER-SETname

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

DIRECTORY /XFERMODE[ filespec ]

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

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

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

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

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

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

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

SET TRANSFER TRANSLATION{ON, OFF}

Enables and disables file-transfer character-set translation. It is
enabled by default.

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

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

send /transparent oofa.txt

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

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

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

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

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

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

SEND /TYPE:BINARY *.*

Sends only binary files, skipping over text files.

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

DIRECTORY /TYPE:TEXT

Lists only text files but not binary files.

DELETE /TYPE:BINARY foo.*

Deletes all foo.* files that are regular binary files but does not
delete any text files.

CHMOD /TYPE:BINARY 775 *

(UNIX) Changes the permissions of all binary files to 775.

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

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

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

cd "c:\Program Files"

C-Kermit previously used braces for this:

cd {c:\Program Files}

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

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

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

"c:\My Directory"

not:

c:\"My Directory"

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

cat th<Tab>

Kermit repaints the filename field like this:

cat "this file"

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

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

cat th<Tab>

Kermit prints:

cat "this "<Beep>

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

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

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

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

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

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

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

SET COMMAND DOUBLEQUOTING OFF

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

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

type *blah<Tab>

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

type ~olga/x<Tab>

is repainted as (e.g.):

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

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

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

take commandfile arg1 arg2 ...

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

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

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

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

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

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

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

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

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

Only Up and Down arrow keys are accepted.

Only 7-bit ANSI arrow-key sequences are understood (ESC followed by
[ or uppercase letter O, followed by uppercase letter
A or (up) B (down).

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

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

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

CATfilename

Equivalent to TYPE /NOPAGE.

CDUP

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

CHMOD[ switches ] permission files

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

CLEAR KEYBOARD-BUFFER

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

CONTINUE

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

COPY, RENAME, and TRANSLATE

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

COPY /APPENDsource destination

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

DELETE /ASK

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

DELETE /DIRECTORIES

Deletes not only files but also directories.

DELETE /RECURSIVE

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

DELETE /SUMMARY

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

DELETE /TREE

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

DELETE /TYPE:BINARY

Delete only regular binary files (requires FILE SCAN ON).

DELETE /TYPE:TEXT

Delete only regular text files (requires FILE SCAN ON).

DIRECTORY[ switches ] [ filespec
[ filespec [ filespec ... ] ] ]

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

DIRECTORY /NORECURSIVExxx

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

DIRECTORY /FOLLOWLINKSxxx

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

DIRECTORY /NOFOLLOWLINKSxxx

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

DIRECTORY /OUTPUT:filename

Sends the results of the DIRECTORY command to the given file.

DIRECTORY /SUMMARY

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

Explains the firewall negotiation capabilities of your version of Kermit.

KCD[ symbolic-directory-name ]

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

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

MOREfilename

Equivalent to TYPE /PAGE.

ORIENTATION

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

PROMPT[ text ]

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

REMOTE SET MATCH{DOTFILE, FIFO}{ON, OFF}

Allows the client to tell the server whether wildcards
sent to the server should match dot files (files whose names begin with
period) or FIFOs (named pipes). See SET MATCH.

SET ATTRIBUTE RECORD-FORMAT{ON, OFF}

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

SET CD HOME[ directory ]

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

SET EXIT HANGUP{OFF, ON}

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

SET FILE EOF{CTRL-Z, LENGTH}

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

SET FILE LISTSIZEnumber

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

SET FILE STRINGSPACEnumber

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

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

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

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

SET OPTIONS DIRECTORY /DOTFILES

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

SET QUIET ON

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

SET HOST connection progress messages.

"Press the X or E key to cancel" file-transfer message.

REMOTE CD response.

REMOTE LOGIN response.

SET RECEIVE PERMISSIONS{ON, OFF}

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

SET ROOTdirectory

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

SET SEND PERMISSIONS{ON, OFF}

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

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

SHOW COMMUNICATIONS

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

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

TAIL[ switches ] filename

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

TRANSMIT /NOECHO[ other switches ] filename

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

TRANSMIT /NOWAIT[ other switches ] filename

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

TRANSMIT /NOWAIT /NOECHO /BINARY[ other switches ] filename

When the TRANSMIT command is given with the /NOWAIT, /NOECHO, and /BINARY
switches, this activates a special "blast the whole file out the
communications connection all at once" mode that Kermit didn't have prior
to version 8.0. There has been increasing demand for this type of
transmission with the advent of devices that expect image (e.g. .JPG)
or sound (e.g. .MP3) files as raw input. The obvious question is:
how does the receiving device know when it has the whole file? This depends
on the device, of course; usually after a certain amount of time elapses with
nothing arriving, or else when Kermit hangs up or closes the connection.

TYPE /CHARACTER-SET:name

Allows you to specify the character set in which the file to be typed
is encoded.

TYPE /NUMBER

Adds line numbers.

TYPE /OUTPUT:filename

Sends the results of the TYPE command to the given file.

TYPE /TRANSLATE-TO:name

Used in conjunction with TYPE /CHARACTER-SET:xxx; allows
you to specify the character set in which the file is to be displayed.

TYPE /TRANSPARENT

Used to disable character-set translation in the TYPE command, which
otherwise can take place automatically based on file scanning, even when
/CHARACTER-SET and /TRANSLATE-TO switches are not given.

VOIDtext

Parses the text, evaluating any backslash items in it (such as function
calls) but doesn't do anything further, except possibly printing error
messages. Useful for invoking functions that have side effects without using
or printing their direct results, e.g. "void \fsplit(\%a,&a)".

Symbolic Links in UNIX

The UNIX versions of C-Kermit have had /FOLLOWLINKS and
/NOFOLLOWLINKS switches added to several commands to control
the treatment of symbolic links. Different commands deal differently with
symbolic links:

Kermit SEND, FTP MPUT

/NOFOLLOWLINKS is the default, which means symbolic links are
skipped entirely. The alternative, /FOLLOWLINKS, should be used with
caution, since an innocent link might point to a whole file system, or it
might cause a loop. There is no way in Kermit or FTP protocol to send the
link itself. We either skip them or follow them; we can't duplicate them.

DIRECTORY

/NOFOLLOWLINKS is the default, which means the DIRECTORY command
lists symbolic links in a way that shows they are links, but it does not
follow them. The alternative, /FOLLOWLINKS, follows links and gives
information about the linked-to directories and files.

DELETE, RMDIR

The DELETE command does not have link-specific switches. DELETE never
follows links. If you tell Kermit to delete a symbolic link, it deletes the
link itself, not the linked-to file. Ditto for RMDIR.

COPY

The COPY command behaves just like the UNIX cp command; it always
follows links.

RENAME

The RENAME command behaves just like the UNIX mv command; it operates
on links directly rather than following.

A command cache for frequently used commands plus some related optimizations
increases the speed of compute-bound scripts by anywhere from 50% to 1000%.

The new PROMPT command can be used to set breakpoints for debugging scripts.
If executed in a command file or macro, it gives you an interactive command
prompt in the current context of the script, with all its variables,
arguments, command stack, etc, available for examination or change, and the
ability to resume the script at any point (END resumes it, Ctrl-C or STOP
cancels it and returns to top level).

The new Ctrl-C trapping feature (Section 8.14) lets you
intercept interruption of scripts. This can be used in combination with the
PROMPT command to debug scripts. Example:

define ON_CTRLC {
echo INTERRUPTED BY CTRL-C...
echo The command stack has not yet been rolled back:
show stack
echo Type Ctrl-C again or use the END command to return to top level.
prompt Debug>
}

Adding this ON_CTRL definition to your script lets you interrupt it at any
point and get prompt that is issued at the current command level, so you can
query local variables, etc.

A macro is a way to assign a value to a name, and then use the name to refer
to the value. Macros are used in two ways in Kermit: as "subroutines" or
functions composed of Kermit commands, which are executed, or as variables to
hold arbitrary values -- text, numbers, filenames, etc.

When a macro is to be executed, its name is given as if it were a C-Kermit
command, optionally preceded by the word "do". When a macro is used as a
variable, it must be "escaped" with \m(xxx) (or
equivalent function, e.g. \s(xxx),
\:(xxx), \fdefinition(xxx)),
where xxx is the macro name, for example:

But these are contexts in which only numbers are valid. C-Kermit 8.0 has been
changed to treat non-escaped non-numeric items in strictly numeric contexts as
macro names. So it is now possible (but not required) to omit the
\m(...) notation and just use the macro name in these contexts:

which reduces the backslash count to less than half. The final statement
in the loop could be written ".\&a[i] ::= tmp" if the array
contained only numbers (since ::= indicates arithmetic expression
evaluation).

Also, now you can use floating-point numbers in integer contexts (such as
array subscripts), in which case they are truncated to an integer value (i.e.
the fractional part is discarded).

Macro names used in numeric contexts must not include mathematical operators.
Although it is legal to create a macro called "foo+bar", in a numeric context
this would be taken as the sum of the values of "foo" and "bar". Any such
conflict can be avoided, of course, by enclosing the macro name in
\m(...).

Allows a script to test whether a key was pressed without actually
trying to read it.

IF KERBANG (Unix only)

True if Kermit was started from a Kerbang script. This is useful for
knowing how to interpret the \&@[] and \&_[]
argument vector arrays, and under what conditions to exit.

IF INTEGERn

This is just a synonym for IF NUMERIC, which is true if n contains
only digits (or, if n is a variable, its value contains only digits).

By contrast, IF FLOAT n succeeds if n is a
floating-point number OR an integer (or a variable with floating-point or
integer value). Therefore, IF FLOAT should be used whenever any kind of
number is acceptable, whereas IF INTEGER (or IF NUMERIC) when only an integer
can be used.

The ON_CD macro, if defined, is executed whenever Kermit is given a CD
(change directory) command (8.0.211). Upon entry to this macro, the
directory has already changed and the new directory string is available in
the \v(directory) variable, and also as the first argument
(\%1).

A clarification regarding references to array names (as opposed to array
elements): You can use array-name "abbreviations" like &a only in contexts
that expect array names, like ARRAY commands or array-name function arguments
such as the second argument of \fsplit(). In a LOCAL statement,
however, you have to write \&a[], since "local &a"
might refer to a macro named "&a".

In function arguments, however, you MUST use the abbreviated form:
\fsplit(\%a,&a) or \fsplit(\%a,&a[]). If you
include the backslash (as in "\fsplit(\%a,\&a[])") a parse error
occurs.

Here are the new array-related commands:

IF DECLAREDarrayname

Allows a script to test whether an array has been declared. The arrayname
can be a non-array backslash variable such as \%1 or
\m(name), in which case it is evaluated first, and the result
is treated as the array name. Otherwise, arrayname is treated as in the ARRAY
commands: it can be a,
&a,
&a[],
\&a,
\&a[],
\&a[3],
\&a[3:9],
etc, with the appropriate results in each case. Synonym:IF DCL.

UNDECLAREarrayname

UNDECLARE is a new top-level command to undeclare an array. Previously
this could only be done with "declare\&a[0]" (i.e.
re-declare the array with a dimension of 0).

ARRAY LINKlinkname arrayname

Creates a symbolic link from the array named by linkname (which must be
the name of an array that is not yet declared in the current context) to the
array named by arrayname (which must the name of a currently declared
array that is not itself a link, or a variable containing the name of such
an array). The two names indicate the same array: if you change an array
element, the change is reflected in the link too, and vice versa. If you
undeclare the link, the real array is unaffected. If you undeclare the real
array, all links to it disappear. If you resize an array (directly or
through a link), all links to it are updated automatically.

Array links let you pass array names as arguments to macros. For example,
suppose you had a program that needed to uppercase all the elements of
different arrays at different times. You could write a macro to do this, with
the array name as an argument. But without array links, there would be no way
to refer to the argument array within the macro. Array links make it easy:

The macro declares the array link LOCAL, which means it doesn't conflict with
any array of the same name that might exist outside the macro, and that the
link is destroyed automatically when the macro exits. This works, by the way,
even if the link name and the macro argument name are the same, as long as the
link is declared LOCAL.

As noted, you can't make a link to a nonexistent array. So when writing a
macro whose job is to create an array whose name is passed as an argument, you
must declare the array first (the size doesn't matter as long as it's greater
than 0). Example:

One final improvement allows the macro itself to declare the array (this was
not possible in earlier Kermit releases): if the array name in the DECLARE
command is a variable (and not an array name), or includes variables, the
resulting value is used as the array name. So:

\v(buildid) A date string like "20000808" indicating when C-Kermit was built.
\v(ftime) Current time, secs since midnight, including fraction of second.
\v(iprompt) The current SET PROMPT value
\v(sexp) The most recent S-Expression (see Section 9)
\v(sdepth) The current S-Expression invocation depth (Section 9)
\v(svalue) The value of the most recent S-Expression (Section 9)

Most functions that have "2" in their names to stand for the word "to" can
now also be written with "to", e.g. "\fdelta2secs(),"
\fdeltatosecs()."

\funtabify(string)

(New to 8.0.211) Replaces Horizontal Tab characters in the given string
with spaces based on VT100-like tab stops.

\fverify(s1,s2,n)

As of version 8.0.211, returns -1 if s2 is an empty string.
Previously it returned 0, making \fverify(abc,\%a) look as if
\%a was a string composed of a's, b's, and/or c's when in fact
it contained nothing.

\fcode(string)

As of version 8.0.211, returns 0 if string is empty or missing.
Previously it returned the empty string, which made it unsafe to use in
arithmetic or boolean expressions.

\v(inscale)

New to version 8.0.211, its value is the INPUT SCALE-FACTOR
(Section 8.10), default 1.0.

\fkeywordval(s1,c1) is new to
C-Kermit 8.0. Given a
string s1 of the form "name=value", it creates a macro with the
given name and assigns it the given value. If no value appears after the
equal sign, any existing macro of the given name is undefined. Blanks are
automatically trimmed from around the name and value. The optional c1
parameter is the assignment operator character, equal sign (=) by
default. This function is handy for processing keyword parameters or any
other form of parameter-value pair. Suppose, for example, you want to write
a macro that accepts keyword parameters rather than positional ones:

In this example, all the defaults are set up inside the macro, and therefore
it can be invoked with no parameters at all. But if you want to have the
macro dial a different number, you can supply it as follows:

mydial number=7654321

You can supply any number of keyword parameters, and you can give
them in any order:

\fjoin(&a,s1,n1,n2) is also new; it
creates a string from an array (or a piece of one). &a is the
name of the array (a range specifier can be included); s1 is a
character or string to separate each element in the result string (can be
omitted, in which case the elements are not separated at all), and n1
is a grouping mask, explained below. If s1 is empty or not specified,
the array elements are separated with spaces. If you want the elements
concatenated with no separator, include a nonzero n2 argument. Given
the array:

These can be OR'd (added) together to make any number 0-63 (-1 is treated the
same as 63, 0 means no grouping). If a bit is on, the corresponding kind of
grouping is selected. (If more than 1 bit is set for \fjoin(), only the
lowest-order one is used.)

If you include the same character in the grouping mask and the include list,
the grouping mask takes precedence. Example:

\fsplit() and \fjoin() are "reciprocal" functions. You can
split a string up into an array and join it back into a new string that is
equivalent, as long as \fsplit() and \fjoin() are given
equivalent grouping masks, except that the type of braces might change.
Example:

It is possible to quote separator grouping characters with backslash to
override their grouping function. And of course to include backslash itself
in the string, it must be quoted too. Furthermore, each backslash must be
doubled, so the command parser will still pass one backslash to
\fsplit() for each two that it sees. Here are some examples using
\fsplit() with a grouping mask of 8 (treat parentheses as grouping
characters).

\fsplit() has also been changed to create its array (if one is given)
each time it is called, so now it can be conveniently called in a loop without
having to redeclare the array each time.

Incidentally... Sometimes you might want to invoke \fsplit() in a
situation where you don't care about its return value, e.g. when you just want
to fill the array. Now you can "call" \fsplit() or any other
function with the new VOID command:

void \fsplit(\%a,&a)

\fsplit() and \fjoin() also accept a new, optional 6th
argument, an options flag, a number that can specify a number of
options. So far there is just one option, whose value is 1:

separator-flag

Normally separators are collapsed. So, for example,

\fword(Three little words,2)

returns "little" (the second word). Space is a separator, but there are
multiple spaces between each word. If the value 1 is included in the option
flag, however, each separator counts. If two separators are adjacent, an
empty word is produced between them. This is useful for parsing (e.g.)
comma-separated lists exported from databases or spreadsheets.

In this connection, note that \v(cmdfile) always indicates the most
recently invoked active command file (if any), even if that file is executing
a macro. Similarly, \v(macro) indicates the most recently invoked
macro (if any), even if the current command source is not a macro. The name
of the "caller" of the currently executing object (command file or macro) is:

\fcmdstack(\v(cmdlevel)-1)

and its type is:

\fcmdstack(\v(cmdlevel)-1,1)

To find the name of the macro that invoked the currently executing object,
even if one or more intermediate command files (or prompting levels) are
involved, use a loop like this:

VOID is like ECHO in that all functions and variables in its argument text are
evaluated. but it doesn't print anything (except possibly an error message if
a function was invocation contained or resulted in any errors). VOID sets
FAILURE if it encounters any errors, SUCCESS otherwise.

With an END [ number [ message ] ] command. If a number
is given, the macro succeeds if the number is 0, and fails if it is not zero;
if a number is not given, the macro succeeds.

With a STOP command, which works just like END except it peels
back the command stack all the way to top level.

With a RETURN[ text ] command, in which case the
macro always succeeds.

By running out of commands to execute, in which case the macro succeeds
or fails according the most recently executed command that sets success
or failure.

The same considerations apply to command files invoked by the TAKE command.

If a macro does not execute any commands that set success or failure, then
invoking the macro does not change the current SUCCESS/FAILURE status. It
follows, then, that the mere invocation of a macro does not change the
SUCCESS/FAILURE status either. This makes it possible to write macros to
react to the status of other commands (or macros), for example:

The UNDEFINE command, which previously accepted one variable name, now
accepts a list of them, and also accepts wildcard notation to allow deletion
of variables that match a given pattern.

UNDEFINE[ switches ] name [ name [ name [ ... ] ] ]

Undefines the variables whose names are given. Up to 64 names may be
given in one UNDEFINE command.

If you omit the switches and include only one name, the UNDEFINE command
works as before.

Switches include:

/MATCHING

Specifies that the names given are to treated as patterns rather than
literal variable names. Note: pattern matching can't be used with array
references; use the ARRAY command to manipulate arrays and subarrays.

/LIST

List the name of each variable to be undefined, and whether it was
undefined successfully ("ok" or "error"), plus a summary count at the end.

/SIMULATE

List the names of the variables that would be deleted without actually
deleting them. Implies /LIST.

The UNDEFINE command fails if there were any errors and succeeds otherwise.

The new _UNDEFINE command is like UNDEFINE, except the names
are assumed to be variable names themselves, which contain the names (or parts
of them) of the variables to be undefined. For example, if you have the
following definitions:

define \%a foo
define foo This is some text

then:

undef \%a

undefines the variable \%a, but:

_undef \%a

undefines the macro foo.

Normal Kermit patterns are used for matching; metacharacters include asterisk,
question mark, braces, and square brackets. Thus, when using the /MATCHING
switch, if the names of the macros you want to undefine contain any of these
characters, you must quote them with backslash to force them to be taken
literally. Also note that \%* is not the name of a variable; it is a
special notation used within a macro for "all my arguments". The command
"undef /match \%*" deletes all \%x variables, where x
is 0..9 and a..z. Use "undef /match \%[0-9]" to
delete macro argument variables or "undef /match \%[i-n]" to delete
a range of \%x variables.

As of C-Kermit 8.0.211, the INPUT and MINPUT commands accept a switch:

[M]INPUT /NOMATCH timeout

The /NOMATCH switch allows INPUT or MINPUT to read incoming material
for the specified amount of time, without attempting to match it with any
text or patterns. When this switch is included, the [M]INPUT command
succeeds when the timeout interval expires, with \v(instatus)
set to 1, meaning "timed out", or fails upon interruption or i/o error.

Also in version 8.0.211, there is a new way to apply a scale factor to
[M]INPUT timeouts:

SET INPUT SCALE-FACTOR floating-point-number

This scales all [M]INPUT timeouts by the given factor, allowing
time-sensitive scripts to be adjusted to changing conditions such as
congested networks or different-speed modems without having to change each
INPUT-class command. This affects only those timeouts that are given in
seconds, not as wall-clock times. Although the scale factor can have a
fractional part, the INPUT timeout is still an integer. The new
built-in variable \v(inscale) tells the current INPUT SCALE-FACTOR.

The MINPUT command can be used to search the incoming data stream for several
targets simultaneously. For example:

MINPUT 8 one two three

waits up to 8 seconds for one of the words "one", "two", or "three" to
arrive. Words can be grouped to indicate targets that contain spaces:

MINPUT 8 nineteen twenty "twenty one"

And of course you can also use variables in place of (or as part of) the
target names:

MINPUT 8 \%a \&x[3] \m(foo)

Until now you had to know the number of targets in advance when writing the
MINPUT statement. Each of the examples above has exactly three targets.

But suppose your script needs to look for a variable number of targets. For
this you can use arrays and \fjoin(), described in
Section 8.7. Any number of
\fjoin() invocations can be included in the MINPUT target list, and
each one is expanded into the appropriate number of separate targets each time
the MINPUT command is executed. Example:

declare \&a[10] = one two three
minput 10 foo \fjoin(&a) bar

This declares an array of ten elements, and assigns values to the first three
of them. The MINPUT command looks for these three (as well as the words
"foo" and "bar"). Later, if you assign additional elements to the array, the
same MINPUT command also looks for the new elements.

If an array element contains spaces, each word becomes a separate target.
To create one target per array element, use \fjoin()'s grouping
feature:

C-Kermit now includes a simple script recorder that monitors your commands,
plus your actions during CONNECT mode, and automatically generates a script
program that mimics what it observed. You should think of this feature as a
script-writing ASSISTANT since, as you will see later in
this section, the result generally needs some editing to make it both
secure and flexible. The script recorder is controlled by the new LEARN
command:

LEARN[/ON /OFF /CLOSE] [ filename ]

If you give a filename, the file is opened for subsequent recording.
The /ON switch enables recording to the current file (if any); /OFF
disables recording. /CLOSE closes the current script recording file
(if any). If you give a filename without any switches, /ON is assumed.

The /OFF and /ON switches let you turn recording off and on during a session
without closing the file.

When recording:

All commands that you type (or recall) at the prompt are recorded in
the file except:

LEARN commands are not recorded.

The CONNECT command is not recorded.

The TELNET command is converted to SET HOST /NETWORK:TCP.

Commands obtained from macros or command files are not recorded.

During CONNECT:

Every line you type is converted to an OUTPUT command.

The last prompt before any line you type becomes an INPUT command.

Timeouts are calculated automatically for each INPUT command.

A PAUSE command is inserted before each OUTPUT command just to be safe.

Thus the script recorder is inherently line-oriented. It can't be used to
script character-oriented interactions like typing Space to a "More?" prompt
or editing a text file with VI or EMACS.

But it has advantages too; for example it takes control characters into
account that might not be visible to you otherwise, and it automatically
converts control characters in both the input and output streams to the
appropriate notation. It can tell, for example that the "$ "
prompt on the left margin in UNIX is really {\{13}\{10}$ },
whereas in VMS it might be {\{13}\{10}\{13}$ }. These sequences
are detected and recorded automatically.

A learned script should execute correctly when you
give a TAKE command for it. However, it is usually appropriate to edit the
script a bit. The most important change would be to remove any passwords from
it. For example, if the script contains:

The LEARN command can't do this for you since it knows nothing about
"content"; it only knows about lines and can't be expected to parse or
understand them -- after all, the Password prompt might be in some other
language. So remember: if you use the LEARN command to record a login script,
be sure edit the resulting file to remove any passwords. Also be sure to
delete any backup copies your editor or OS might have made of the file.

Other manual adjustments might also be appropriate:

If the target of an INPUT command can vary, you can replace the INPUT
command with MINPUT and the appropriate target list, and/or the target
with a \fpattern(). For example, suppose you are dialing a number
that can be answered by any one of 100 terminal servers, whose prompts are
ts-00>, ts-01>, ts-02>, ...
ts-99>. The script records a particular one of these, but you
want it to work for all of them, so change (e.g.):

INPUT 10 ts-23> ; or whatever

to:

INPUT 10 \fpattern(ts-[0-9][0-9]>)

The INPUT timeout values are conservative, but they are based only on
a single observation; you might need to tune them.

The PAUSE commands might not be necessary, or the PAUSE interval might
need adjustment.

In case you made typographical errors during recording, they are
incorporated in your script; you can edit them out if you want to.

Here is a sample script generated by Kermit ("learnvms.ksc") in which a Telnet connection is made to a VMS computer, the
user logs in, starts Kermit on VMS, sends it a file, and then logs out:

The commands generated by Kermit during CONNECT (INPUT, IF FAIL, PAUSE, and
OUTPUT) have uppercase keywords; the commands typed by the user are in
whatever form the user typed them (in this case, lowercase).

A pattern is a character string that is used to match other strings. Patterns
can contain metacharacters that represent special actions like "match
any single character", "match zero or more characters", "match any single
character from a list", and so on. The best known application of patterns is
in file specifications that contain wildcards, as in "send*.txt", meaning "send all files whose names end with .txt".

Patterns are also used in increasingly many other ways, to the extent it is
useful to point out certain important distinctions in the ways in which they
are used:

Anchored Patterns

If an anchored pattern does not begin with "*", it must match the
beginning of the string, and if it does not end with "*", it must
match the end of the string. For example, the anchored pattern "abc"
matches only the string "abc", not "abcde" or
"xyzabc" or "abcabc". The anchored pattern "abc*"
matches any string that starts with "abc"; the anchored pattern
"*abc" matches any string that ends with "abc"; the
anchored pattern "*abc*" matches any string that contains
"abc" (including any that start and/or end with it).

Floating Patterns

A floating pattern matches any string that contains a substring that
matches the pattern. In other words, a floating pattern has an implied
"*" at the beginning and end. You can anchor a floating pattern
to the beginning by starting it with "^", and you can anchor it
to the end by ending it with "$" (see examples below).

Wildcards

A wildcard is an anchored pattern that has the additional property that
"*" does not match directory separators.

This terminology lets us describe Kermit's commands with a bit more precision.
When a pattern is used for matching filenames, it is a wildcard, except in the
TEXT-PATTERNS and BINARY-PATTERNS lists and
/EXCEPT: clauses, in which case directory separators are not
significant (for example, a BINARY-PATTERN of "*.exe"
matches any file whose name ends in .exe, no matter how deeply it
might be buried in subdirectories). When Kermit parses a file specification
directly, however, it uses the strict wildcard definition. For example,
"send a*b" sends all files whose names start with "a" and
end with "b" in the current directory, and not any files whose names
end with "b" that happen to be in subdirectories whose names start
with "a". And as noted, wildcards are anchored, so "delete
foo" deletes the file named "foo", and not all files whose names
happen to contain "foo".

Most other patterns are anchored. For example:

if match abc bc ...

does not succeed (and you would be surprised if it did!). In fact, the only
floating patterns are the ones used by commands or functions that search for
patterns in files, arrays, or strings. These include:

The GREP and TYPE /MATCH commands.

The \fsearch(), \frsearch(), and \farraylook()
functions.

Thus these are the only contexts in which explicit anchors ("^" and
"$") may be used:

grep abc *.txt

Prints all lines containing "abc" in all files whose names
end with ".txt".

grep ^abc *.txt

Prints all lines that start with "abc" in all
".txt" files.

grep abc$ *.txt

Prints all lines that end with "abc" in all
".txt" files.

grep ^a*z$ *.txt

Prints all lines that start with "a" and end with
"z" in all ".txt" files.

Similarly for TYPE /PAGE, /fsearch(), /frsearch(),
and \farraylook().

Here is a brief summary of anchored and floating pattern equivalences:

C-Kermit's comprehension of date-time formats is considerably expanded in
version 8.0. Any command that reads dates, including the DATE
command itself, or any switch, such as the /BEFORE: and
/AFTER: switches, or any function such as \fcvtdate(), now
can understand dates and times expressed in any ISO 8601 format, in Unix
"asctime" format, in FTP MDTM format, and in practically any format used in
RFC 822 or RFC 2822 electronic mail, with or without timezones, and in a great
many other formats as well. HELP DATE briefly summarizes the
acceptable date-time formats.

Furthermore, C-Kermit 8.0 includes a new and easy-to-use form of date-time
arithmetic, in which any date or time can be combined with a "delta time",
to add or subtract the desired time interval (years, months, weeks, days,
hours, minutes, seconds) to/from the given date. And new functions are
available to compare dates and to compute their differences.

As you can imagine, all this requires quite a bit of "syntax". The basic
format is:

[ date ] [ time ] [ delta ]

Each field is optional, but in most cases (depending on the context) there
must be at least one field. If a date is given, it must come first.
If no date is given, the current date is assumed. If no time is given, an
appropriate time is supplied depending on whether a date was supplied. If no
delta is given, no arithmetic is done. If a delta is given without a date or
time, the current date and time are used as the base.

Date-time-delta fields are likely to contain spaces (although they need not;
space-free forms are always available). Therefore, in most contexts -- and
notably as switch arguments -- date-time information must be enclosed in
braces or doublequotes, for example:

send /after:"8-Aug-2001 12:00 UTC" *.txt

Kermit's standard internal format for dates and times is:

yyyymmdd hh:mm:ss

for example:

20010208 10:28:01

Date-times can always be given in this format. yyyy is the 4-digit year,
mm is the two-digit month (1-12; supply leading zero for Jan-Sep), dd is the
2-digit day (leading zero for 1-9), hh is the hour (0-23), mm the minute
(0-59), ss the second (0-59), each with leading zero if less than the field
width. The date and time can be separated by a space, an underscore, a colon,
or the letter T. The time is in 24-hour format. Thus the various quantities
are at the following fixed positions:

This is the format produced by the DATE command and by any function that
returns a date-time. It is suitable for lexical comparison and sorting, and
for use as a date-time in any Kermit command. When this format is given as
input to a command or function, various date-time separators (as noted) are
accepted:

This is the date-time format supplied by FTP servers that support the
(not yet standard but widely used nevertheless) MDTM command, by which the FTP
client asks for a file's modification time:

yyyymmddhhmmss[.ffff]

where yyyy is the 4-digit year, mm is the 2-digit month, and so on, exactly
14 digits long. An optional fractional part (fraction of second) may also be
included, separated by a decimal point (period). Kermit rounds to the nearest
second. Example:

The date, if given, must precede the time and/or delta, and
can be in many, many formats. For starters, you can use several
symbolic date names in place of actual dates:

NOW

This is replaced by the current date and time. The time can not be
overriden (if you want to supply a specific time, use TODAY
rather than NOW).

TODAY

This is replaced by the current date and a default time of 00:00:00
is supplied, but can be overridden by a specific time; for example, if
today is 8 February 2002, then "TODAY" is
"20020802 00:00:00"
but "TODAY 10:28" is "20020802 10:28:00".

TOMORROW

Like TODAY, but one day later (if
today is 8 February 2002, then "TOMORROW" is
"20020803 00:00:00"
but "TOMORROW 16:30" is "20020803 16:30:00").

YESTERDAY

Like TODAY, but one day earlier.

MONDAY, TUESDAY, WEDNESDAY, ..., SUNDAY

The date on the given day of the week, today or later. A default time
of 00:00:00 is supplied but can be overridden. Example:
"SATURDAY 12:00" means next Saturday (or today, if today is Saturday)
at noon.

You can give an explicit date in almost any conceivable format,
but there are some rules:

If a date is given, it must have three fields: day, month, and year;
the order can vary (except that the month can not be last).

If names are used for days, months, etc, they must be English.

The year must lie between 0000 and 9999, inclusive.

All calendar calculations use Gregorian dating, so calculated dates
for years prior to 1582 (or later, depending on the country) will not agree
with historical dates. Other forms of dating (e.g. Hebrew, Chinese) are not
supported.

Various date-field separators are accepted: hyphen, slash, space, underscore,
period. The same field separator (if any) must be used in both places; for
example 18-Sep-2001 but not 18-Sep/2001. Months can be numeric (1-12) or
English names or abbreviations. Month name abbreviations are normally three
letters, e.g. Apr, May, Jun, Jul. Capitalization doesn't matter.

In all-numeric dates with the year last, such as 18/09/2001, Kermit identifies
the year because it's 4 digits, then decides which of the other two numbers is
the month or day based on its value. If both are 12 or less and are unequal,
the date is ambiguous and is rejected. In all-numeric dates with the year
first, the second field is always the month and the third is the day. The
month never comes last. A date with no separators is accepted only if it is
all numeric and has exactly eight digits, and is assumed to be in
yyyymmdd format.

20010918 (18-Sep-2001 00:00:00)

or 14 digits (as in FTP MDTM format):

20010918123456 (18-Sep-2001 12:34:56)

You can always avoid ambiguity by putting the year first, or by
using an English, rather than numeric, month. A date such as 09/08/2001
would be ambiguous but 2001/09/08 is not, nor is 09-Aug-2001.

Until the late 1990s, it was common to encounter 2-digit years, and
these are found to this day in old e-mails and other documents. Kermit
accepts these dates if they have English months, and interprets them according
to the windowing rules of RFC
2822: "If a two digit year is encountered whose value is between 00 and
49, the year is interpreted by adding 2000, ending up with a value between
2000 and 2049. If a two digit year is encountered with a value between 50 and
99, or any three digit year is encountered, the year is interpreted by adding
1900."

If you need to specify a year prior to 1000, use leading zeros to ensure
it is not misinterpreted as a "non-Y2K-compliant" modern year:

The basic time format is hh:mm:dd; that is hours, minutes,
seconds, separated by colons, perhaps with an optional fractional second
separated by a decimal point (period). The hours are in 24-hour format; 12 is
noon, 13 is 1pm, and so on. Fields omitted from the right default to zero.
Fields can be omitted from the left or middle by including the field's
terminating colon. Examples:

If a time is given, it can (but need not) be followed by a time zone
designator. If no time zone is included, the time is treated as local time
and no timezone conversions are performed.

The preferred time zone designator is the UTC Offset, as specified in
RFC 2822: a plus sign or
minus sign immediately followed by exactly four decimal digits, signifying
the difference in hh (hours) and mm (minutes) from Universal Coordinated Time
(UTC, also known as Greenwich Mean Time, or GMT), with negative numbers to
the West and positive numbers to the East. For example:

Fri, 13 Jul 2001 12:54:29 -0700

indicates a local time of 12:54:29 that is 07 hours and 00 minutes
behind (less than, East of) Universal Time. The space is optional, so the
example could also be written as:

Fri, 13 Jul 2001 12:54:29-0700

The following symbolic time zones are also accepted, as specified by
RFC 2822 and/or in
ISO 8601:

Note that GMT, Z, UTC, and UT all express the same concept: standard (not
daylight) time at the Zero Meridian. UTC, by the way, is an international
standard symbol and does not correspond to the order of the English words,
Universal Coordinated Time, but it happens to have the same initial letters as
these words. Of course hundreds of other symbolic timezones and variations
exist, but they are not standardized, and are therefore not supported by
Kermit.

When a time zone is included with a time, the time is converted to local
time. In case the conversion crosses a midnight boundary, the date is
adjusted accordingly. Examples converting to EST (Eastern USA Standard Time =
-0500):

Unlike most of Kermit's other date-time conversions, timezone knowledge
(specifically, the offset of local time from UTC) is embodied in the
underlying operating system, not in Kermit itself, and any conversion errors
in this department are the fault of the OS. For example, most UNIX
platforms do not perform conversions for years prior to 1970.

Date/time expressions can be composed of a date and/or time and a delta
time, or a delta time by itself. When a delta time is given by itself, it
is relative to the current local date and time. Delta times have the
following general format:

{+,-}[number units][hh[:mm[:ss]]]

In other words, a delta time always starts with a plus or minus sign, which is
followed by a "part1", a "part2", or both. The "part1", if given, specifies a
number of days, weeks, months, or years; "part2" specifies a time in
hh:mm:ss notation. In arithmetic terms, these represents some
number of days or other big time units, and then a fraction of a day expressed
as hours, minutes, and seconds; these are to be added to or subtracted from
the given (or implied) date and time. The syntax is somewhat flexible,
as shown by the following examples:

The words "week", "month", and "year" can be used like "day" in the examples
above. A week is exactly equivalent to 7 days. When months are specified,
the numeric month number of the date is incremented or decremented by the given
number, and the year and day adjusted accordingly if necessary (for example,
31-Jan-2001 +1month = 03-Mar-2001 because February does not have 31 days).
When years are specified, they are added or subtracted to the base year.
Examples (assuming the current date is 10-Aug-2001 and the current time is
19:21:11):

and mean "add a day plus 3 hours, 23 minutes, and 1 second" to the given date.

Note that delta times are not at all the same as UTC offsets; the former
specifies an adjustment to the given date/time and the latter specifies that
the local time is a particular distance from Universal Time, for example:

If you give a time followed by a modifier that starts with a + or
- sign, how does Kermit know whether it's a UTC offset or a delta
time? It is treated as a UTC offset if the sign is followed by exactly four
decimal digits; otherwise it is a delta time. Examples (for USA Eastern
Daylight Time):

The first example says that at some unknown place which is 8 hours ahead of
Universal Time, the time is 12:34:56, and this corresponds to 16:34:56 in
Eastern Daylight time. The second example says to subtract 8 hours from the
local time. The third and fourth are delta times because, even though a colon
is not included, the time does not consist of exactly 4 digits.

When a delta time is written after a timezone, however, there is no
ambiguity and no syntax distinction is required:

Obviously a great many combinations of date, time, time zone, and delta time
are possible, as well as many formatting options. The purpose of all this
flexibility is to comply with as many standards as possible -- Internet RFCs,
ISO standards, and proven corporate standards -- as well as with notations
commonly used by real people, in order that dates and times from the widest
variety of sources can be assigned to a variable and used in any date-time
field in any Kermit command.

You can test any date-and/or-time format with the DATE command, which converts
it to standard yyyymmdd hh:mm:ss format if it is understood, or else gives an
explicit error message (rather than just "BAD DATE" as in previous C-Kermit
releases) to indicate what is wrong with it. Examples (on Tuesday, 31 July
2001 in New York City, Eastern Daylight Time, UTC -0400):

In the following descriptions, date-time function arguments are the
same free-format date-time strings discussed above, with the same defaults
for missing fields. They are automatically converted to standard format
internally prior to processing.

\fcvtdate(d1)

Converts the date-time d1 to standard format and local time.
This function is not new, but now it accepts a wider range of argument
formats that can include timezones and/or delta times.
If the first argument is omitted, the current date and time are assumed. The
optional second argument is a format code for the result:

Converts the date-time d1 to Universal Coordinated Time (UTC), also
known as GMT or Zulu or Zero-Meridian time. The default d1 is NOW.
If d1 is a valid date-time, the UTC result is returned in standard
format, yyyymmdd hh:ss:mm.

\fcmpdates(d1,d2)

Compares two free-format date-times, d1 and d2, and, if
both arguments are valid, returns a number:
-1 if d1 is earlier than (before) d2;
0 if d1 is the same as d2;
1 if d1 is later than (after) d2.

\fdiffdates(d1,d2)

Computes the difference between two free-format date-times, d1 and
d2. If both arguments are valid, returns a delta time which is
negative if d1 is earlier than (before) d2 and positive
otherwise. If d1 and d2 are equal, the result is
"+0:00". Otherwise, the result consists of the number of days,
hours, minutes, and seconds that separate the two date-times. If the
number of days is zero, it is omitted. If the number of days is nonzero
but the hours, minutes, and seconds are all zero, the time is omitted.
if the seconds are zero, they are omitted.

\fdelta2secs(dt)

Converts a delta time to seconds. For example, "+1d00:00:01"
to 86401. Valid delta times must start with a + or - sign.
Days are accepted as time units, but not years, months, or weeks. If the
result would overflow a computer long word (as would happen with 32-bit
long words when the number of days is greater than 24854), the function fails.

HINT: Although Kermit has a number of built-in date and time
variables, it doesn't have a single one suitable for writing a timestamp.
For this you would normally use something like "\v(ndate) \v(time)".
But \fcvtdate() (with no arguments) is equivalent: it returns the
current date and time in yyyymmdd hh:mm:ss format,
suitable for time stamping.

Brief explanation: Line 1 converts the macro argument, a free-format
date-time, to standard-format local time. Line 2 appends the "UTC" timezone
to the local time and converts the result to local time. In other words, we
take the same time as the local time, but pretend it's UTC time, and convert
it to local time. For example, if New York time is 4 hours ahead of UTC, then
6:00pm New York time is 2:00pm UTC. Line 3 gets the difference of the two
results (e.g. "+04:00"). Line 4 appends the difference (delta time) to the
local time, and converts it again, which adds (or subtracts) the UTC offset to
the given time. Line 5 displays the result.

Here's a script that opens a web page, gets its headers into an array,
scans the array for the "Last-Modified:" header, and interprets it:

As you can see, Kermit had no trouble decoding the date-time-string from the
website, converting to local time, and converting back to UTC with no
conflicts or loss of information. If it had been in any other known format,
the result would have been the same.

Now suppose we want to download the web page only if it is newer than
our local copy. The \fdate(filename) function (which
returns the modification date-time of the given file) and the
new \fcmpdates() function make it easy. Insert the following
just before the BREAK statement:

This says, "if 0 is less than the comparison of the remote file date
and the local file date, get the remote file, otherwise skip it." And it
automatically reconciles the time-zone difference (if any).

It would be nice to be able to extend this script into a general-purpose
website updater, but unfortunately HTTP protocol doesn't provide any mechanism
for the client to ask the server for a list of files, recursive or otherwise.

Normally when you type Ctrl-C and Kermit is in command mode (as opposed to
CONNECT mode) with COMMAND INTERRUPTION ON (as it is unless you have set it
OFF), Kermit interrupts any command that is currently in progress, and if a
command file or macro is executing, rolls the command stack back to top level,
closing all open command files, deactivating all macros, deallocating all
local variables and arrays, and leaving you at the command prompt.

Suppose, however, you want certain actions to occur when a script is
interrupted; for example, closing open files, writing log entries, or
displaying summary results. You can do this by defining a macro named
ON_CTRLC. When Ctrl-C is detected, and a macro with this name is defined,
Kermit executes it from the current command level, thus giving it full
access to the environment in which the interruption occurred, including local
variables and open files. Only when the ON_CTRLC macro completes execution
is the command stack rolled back to top level.

Once the ON_CTRLC macro is defined, it can be executed only once. This is to
prevent recursion if the user types Ctrl-C while the ON_CTRLC macro is
executing. If you type Ctrl-C while the Ctrl-C macro is active, this does not
start a new copy of ON_CTRLC; rather, it returns to the top-level command
prompt. After the ON_CTRLC macro returns, it has been removed from the macro
table so if you want to use it again or install a different Ctrl-C trap, you
must execute a new DEFINE ON_CTRLC command. In any case, as always when you
interrupt a script with Ctrl-C, its completion status is FAILURE.

Normally the ON_CTRLC macro would be defined in the command file or macro to
which it applies, and should be declared LOCAL. This way, if the command file
or macro completes successfully without being interrupted, the ON_CTRLC
definition disappears automatically. Otherwise the definition would still be
valid and the macro would be executed, probably out of context, the next time
you typed Ctrl-C.

Here's a simple example of a command file that sets a Ctrl-C trap for itself:

This section is primarily for those who want to write calculation-intensive
scripts, especially if they require floating-point arithmetic, and/or for
those who are familiar with the LISP programming language.

Ever since C-Kermit version 5 was released in 1988, scripting has been one of
its major attractions, and arithmetic is a key part of it. Versions 5 and 6
included integer arithmetic only, using traditional algebraic notation, e.g.:

echo \fevaluate(3*(2+7)/2)
13

C-Kermit 7.0 added support for floating-point arithmetic, but only through
function calls:

echo \ffpdivide(\ffpmultiply(3.0,\ffpadd(2.0,7.0)),2.0)
13.5

C-Kermit 8.0 introduces a third form of arithmetic that treats integers and
floating-point numbers uniformly, is easier to read and write, and executes
very quickly:

(/ (* 3 (+ 2 7)) 2)
13.5

But first some background.

The Kermit command and scripting language differs from true programming
languages (such as C or Fortran) in many ways; one of the most prominent
differences is the way in which variables are distinguished from constants.
In a command language, words are taken literally; for example, the Unix shell:

cat foo.bar

displays the file named foo.bar. Whereas in a programming language like C,
words are assumed to be variables:

s = foo.bar; /* Assigns the value of foo.bar to the variable s */

To make a programming language take words literally, you have to quote or
"escape" them:

s = "foo.bar"; /* Assigns a pointer to the string "foo.bar" to the variable s */

The opposite holds for command languages: to get them to treat a word as
a variable rather than a constant, you have to escape them. For example,
in the Unix shell:

In other words, character strings (such as "foo" above) are interpreted as
literal strings, rather than variable names, except in special commands like
DEFINE that deal specifically with variable names (or in numeric contexts as
explained in Section 8.2). The special "escape" character
(dollar sign ($) for the shell, backslash (\) for Kermit)
indicates that a variable is to be replaced by its value.

The requirement to escape variable names in command languages normally does
not impose any special hardship, but can add a considerable notational burden
to arithmetic expressions, which are typically full of variables. Especially
in Kermit when floating point numbers are involved, where you must use special
\ffpxxx() functions, e.g. "\ffpadd(\m(a),\m(b))"
rather than the simple "+" operator to add two floating-point numbers
together, because the original arithmetic handler doesn't support floating
point (this might change in the future). To illustrate, the general formula
for the area of a triangle is:

sqrt(s * (s - a) * (s - b) * (s - c))

where a, b, and c are the lengths of the triangle's three sides and:

s = (a + b + c) / 2

Except in special cases (e.g. a = 3, b = 4, c = 5), the result has a
fractional part so the computation must be done using floating-point
arithmetic. We can create a Kermit 7.0 function for this as follows:

But as you can see, this is rather cumbersome. Note, in particular, that
arithmetic functions like \ffpadd(), \ffpmul(), etc, take
exactly two operands (like their symbolic counterparts + and
*), so obtaining the product of three or more numbers (as we do in
this case) is awkward.

Using the alternative S-Expression notation, we can reduce this to a form that
is both easier to read and executes faster (the details are explained later):

In both examples, the \%1..3 variables are the normal Kermit macro
arguments, referenced by the normal escaping mechanism. For increased
readability, we can also assign the macro arguments \%1,
\%2, and \%3 to the letters a, b, and c corresponding to our
formula:

And now the Kermit function reads almost like the original formula. Here
Kermit behaves more like a regular programming language. In an S-Expression,
macro names need not be escaped when they are used as the names of numeric
variables.

The S-Expression concept is borrowed from the Lisp programming language.
"S-Expression" is short for Symbolic Expression (itself sometimes shortened
to SEXP). S-Expressions provide a kind of Alternative Mini-Universe within
the Kermit command language when the regular rules don't apply, a universe
enclosed in parentheses.

C-Kermit does not pretend to be a full Lisp interpreter; only the arithmetic
parts of Lisp have been incorporated: S-Expressions that operate on numbers
and return numeric values (plus extensibility features described in
Section 9.8, which allow some degree of string processing).

An S-Expression is a list of zero or more items, separated by spaces, within
parentheses. Examples:

()
(1)
(a)
(+ a 1)
(* 2 a b)

If the S-Expression is empty, it has the NIL (empty) value. If it is not
empty and the first item is an operator (such as + or *),
there can be zero or more subsequent items, called the operands:

(+ 1 2)

Here the operator is "+" and the operands are "1" and "2", and the value of
the S-Expression is the value of the operation (in this case 3). The operator
always comes first, which is different from the familiar algebraic notation;
this because S-Expression operators can have different numbers of operands:

(+ 1)
(+ 1 2)
(+ 1 2 3 4 5 6 7 8 9)

If the first item in the S-Expression is not an operator, then it must be a
variable or a number (or a macro; see Section 9.8), and
the S-Expression can only contain one item; in this case, the S-Expression's
value is the value of the variable or number:

(a)
(3)

Operands can be numbers, variables that have numeric values, functions that
return numbers, or other S-Expressions. To illustrate an S-Expression within
an S-Expression, observe that:

(+ 1 2)

is equivalent to any of the following (plus an infinite number of others):

(+ 1 (+ 1 1))
(+ (- 3 2) (/ 14 (+ 3 4)))

S-Expressions can be nested to any reasonable level; for example, the value of
the following S-Expression is 64:

(- (* (+ 2 (* 3 4)) (- 9 (* 2 2))) 6)

Operators have no precedence, implied or otherwise, since they can't be mixed.
The only exceptions are unary + and -, which simply indicate
the sign of a number:

(* 3 -1)

Order of evaluation is specified entirely by parentheses, which are
required around each operator and its operands:
(+ a (* b c))
instead of
(a + b * c).

S-Expressions provide a simple and isolated environment in which Kermit's
macro names can be used without the \m(...) escaping that is normally
required. Given:

define a 1
define b 2
define c 3

Then:

(+ \m(a) \m(b) \m(c))

is equivalent to:

(+ a b c)

Within an S-Expression, as in other strictly numeric contexts (Section 8.2), any operand that starts with a letter is
treated as a Kermit macro name. In this context, abbreviations are not
accepted; variable names must be spelled out in full. Alphabetic case is not
significant; "a" and "A" are the same variable, but both are different from
"area".

Of course, regular Kermit variables and functions can be used in S-Expressions
in the normal ways:

(* \v(math_pi) (^ \%r 2)) ; Area of a circle with radius \%r
(+ \fjoin(&a)) ; Sum of all elements of array \&a[]

Normally, if all numbers in an S-Expression are integers, the result is an
integer:

(+ 1 1) ; Result is 2
(/ 9 3) ; Result is 3

If any of the operands is floating point, however, the result is also
floating point:

(+ 1 1.0) ; Result is 2.0
(/ 9.0 3) ; Result is 3.0

If all the operands are integers but the result has a fractional part,
the result is floating point:

(/ 10 3) ; Result is 3.333333333333333

To force an integer result in such cases, use the TRUNCATE operator:

(truncate (/ 10 3)) ; Result is 3

Similarly, to force a computation to occur in floating point, you can
coerce one of its operands to FLOAT:

(+ 1 (float 1)) ; Result is 2.0

The result is also floating point if the magnitude of any integer operand,
intermediate result, or the result itself, is larger than the maximum for the
underlying machine architecture:

(^ 100 100)

If the result is too large even for floating-point representation, "Infinity"
is printed; if it is too small to be distinguished from 0, 0.0 is returned.

Large numbers can be used and large results generated, but they are accurate
only to the precision of the underlying machine. For example, the result of:

(+ 111111111111111111111 222222222222222222222)

should be 333333333333333333333, but 333333333333333300000.0 is produced
instead if the machine is accurate to only about 16 decimal digits, even with
coercion to floating-point. The order of magnitude is correct but the least
significant digits are wrong. The imprecise nature of the result is indicated
by the ".0" at the end. Contrast with:

S-Expressions may be given as commands to C-Kermit. Any command whose
first character is "(" (left parenthesis) is interpreted as an
S-Expression.

If you enter an S-Expression at the C-Kermit> prompt, its result
is printed:

C-Kermit>(/ 10.0 3)
3.333333333333333
C-Kermit>

If an S-Expression is executed within a macro or command file, its value is
not printed. However, you can control the printing action with:

SET SEXPRESSION ECHO{AUTO, ON, OFF}

AUTO is the default, meaning print the value at top level only;
ON means always print the value; OFF means never print it.

In any case, the value of the most recent S-Expression (and the S-Expression
itself) may be accessed programmatically through the following variables:

\v(sexpression)

The S-Expression most recently executed.

\v(svalue)

The value of the S-Expression most recently executed.

Besides issuing S-Expressions as commands in themselves, you can also execute
them anywhere within a Kermit command, but in this case they must be enclosed
in a function call (otherwise they are taken literally):

\fsexpression(s)

The argument "s" is an S-Expression; the outer parentheses may be omitted.
The value of the S-Expression is returned. Note that since S-Expressions
usually contain spaces, some form of grouping or quoting might be needed in
some contexts:

The IF statement illustrates how to use S-Expressions as (or in) IF or WHILE
conditions:

Although S-Expressions and IF conditions are similar in appearance, they
are not interchangeable. Therefore you must use \fsexpr() to let
Kermit know it's an S-Expression rather than a regular IF condition, or a
boolean or algebraic expression within an IF condition.

In contexts where a single "word" is expected, you must enclose the
\fsexp() invocation in braces if the S-Expression contains spaces (and
most of them do).

If an S-Expression is the last command executed in a macro, its value becomes
the return value of the macro; no RETURN command is needed. Example:

When an S-Expression is entered as a command -- that is, the first nonblank
character of the command is a left parenthesis -- then it is allowed to span
multiple lines, as many as you like, until the first left parenthesis is
matched:

The S-Expression concept lends itself easily to embedding and recursion, but
the depth to which recursion can occur is limited by the resources of the
computer (memory size, address space, swap space on disk) and other factors.
There is no way that C-Kermit can know what this limit is, since it varies not
only from computer to computer, but also from moment to moment. If resources
are exhausted by recursion, C-Kermit simply crashes; there's no way to trap
this error. However, you can set a depth limit on S-Expressions:

SET SEXPRESSION DEPTH-LIMITnumber

Limits the number of times the S-Expression reader can invoke itself
without returning to the given number. The default limit is 1000.
This limit applies to S-Expressions embedded within other S-Expressions
as well as to S-Expressions that invoke recursive macros. If the limit
is exceeded, Kermit prints "?S-Expression depth limit exceeded" and
returns to its prompt. More about recursion in
Section 9.8.

You can also test the depth programmatically:

\v(sdepth)

The current S-Expression invocation depth. The depth includes both nesting
level and recursion. For example, in:
(foo (foo (foo (foo (foo))))), the innermost
(foo) is at depth 5.

Help, completion, and syntax checking are not available within an S-Expression.
If you type ? within an S-Expression, it says:

C-Kermit>(? S-Expression ("help sexp" for details)

As it says, typing "help sexp" will display a brief help text.

The SHOW SEXPRESSION command displays current SET SEXPRESSION settings and
related information.

Opposite of EVAL is the operator that suppresses evaluation of its operand:

QUOTEitem

The value (quote item) is "item". If the item is itself an S-Expression,
the result is the S-Expression with the outer parentheses stripped.
Examples:

(quote) (illegal)
(quote a) a
(quote hello) hello
(quote (this is a string)) this is a string
(quote this is a string) (illegal)

A shorthand notation is also accepted for quoting:'a is equivalent to (quote a). And therefore:'(a b c) is equivalent to (quote (a b c)).
More about quoting in Section 9.8.

STRINGitem

Is a combination of EVAL and QUOTE. It evaluates the item as an
S-Expression, and then puts quotes around the result (more about this
in Section 9.8).

The following operators assign values to variables:

SETQ[ variable [ value [ variable [ value [ ... ] ] ] ] ]

Applies to global variables. For each variable given: if a value
is not given, the variable is undefined. If a value is given, assigns the
value to the variable. The value may be a number, a variable, or anything
that resolves to a number including an S-Expression. Returns the value of the
last assignment. Examples:

The ++ and -- operators are also assignment operators and
work just like SETQ and LET in their interpretations of operators and
operands, but:

Each target variable must already be defined and have a numeric value;

The assignment value is the amount by which to increment or decrement
the variable.

If an assignment value is not given, 1 is used.

If you include more than one variable-value pair in a ++ or
-- expression, every variable (except, optionally, the last) must be
followed by a value.
Examples:

(++ a) Equivalent to (setq a (+ a 1)) and to (++ a 1)
(++ a 2) Equivalent to (setq a (+ a 2))
(-- a (* 2 pi)) Equivalent to (setq a (- a (* 2 pi)))
(++ a 1 b 1 c 1 d) Equivalent to four SETQs incrementing a,b,c,d by 1.

Another group of operators forms the predicates. These return a "truth
value", in which 0 (or NIL) is false, and 1 or any other nonzero number is
true.

The IF operator is similar to Kermit's IF command. If the predicate is
true (i.e. evaluates to a nonzero number), the first S-Expression (s1) is
evaluated and its value is returned. Otherwise, if (s2) is given, it is
evaluated and its value returned; if (s2) is not given, nothing happens
and the NIL (empty) value is returned.

You can group multiple expressions in the s1 and s2 expressions using EVAL
(or "."):

Each operator has its own requirement as to number and type of operands.
In the following table, "number" means any kind of number -- integer or
floating-point -- or a variable, function, macro, or S-Expression that returns
a number; "vname" means variable name, "fpnumber" means a floating-point
number (or anything that resolves to one), and "integer" means integer (or
anything that resolves to one). "truthvalue" means anything that resolves to
a value of zero or an empty value (which indicates false) or a nonzero value
(which indicates true). "any" means any kind of value, including none at all.

OperatorNumber of operandsType of operandsReturns
EVAL (.) 0 or more S-Expression Last value (default NIL)
STRING 1 S-Expression string
QUOTE (') 1 word string
SETQ 0 or more vname value pairs Last value (default NIL)
LET 0 or more vname value pairs Last value (default NIL)
+ 0 or more number number (default 0)
- 0 or more number number (default 0)
* 0 or more number number (see note (1))
/ 2 or more number number
^ 2 or more number number
++ 1 or more vname value pairs Result of last increment
-- 1 or more vname value pairs Result of last decrement
ABS 1 number number
MAX 1 or more number number
MIN 1 or more number number
MOD (%) 2 number number
FLOAT 1 number fpnumber
TRUNCATE 1 number integer
CEILING 1 number integer
FLOOR 1 number integer
ROUND 1 number integer
SQRT 1 number fpnumber
EXP 1 number fpnumber
SIN 1 number fpnumber
COS 1 number fpnumber
TAN 1 number fpnumber
LOG 1 number fpnumber
LOG10 1 number fpnumber
= (==) 1 or more number truthvalue
!= 1 or more number truthvalue
< 1 or more number truthvalue
<= 1 or more number truthvalue
> 1 or more number truthvalue
>= 1 or more number truthvalue
AND (&&) 1 or more truthvalue truthvalue
OR (||) 1 or more truthvalue truthvalue
XOR 2 truthvalue truthvalue
NOT (!) 1 truthvalue truthvalue
& 1 or more number (see note 2) integer
| 1 or more number (see note 2) integer
# 2 number (see note 2) integer
~ 1 number (see note 2) integer
IF 2 or 3 truthvalue,any,any any

As noted elsewhere in this discussion, all backslash items (variables such as
\%a, macro parameters such as \%1, array elements such as \&a[\%i],
built-in variables such as \v(ndate), built-in functions such as \fjoin(),
macro names enclosed in \m(), \s(), or \:(), etc) are evaluated at "top level"
before the S-Expression is sent to the S-Expression reader. To use a
backslash variable as the target of an assignment (e.g. by SETQ, LET, ++, or
--), you must double the backslash, e.g. (setq \\%r 1234). This is discussed
at greater length in the next section.

Thus S-Expression reader generally deals only with macro names (not backslash
items) as variables. It is important to understand how the reader handles
macro names. There are fundamentally two kinds of S-Expressions: those that
contain a single element, such as:

(foo)

and those that contain more than one element:

(foo a b c)

If an S-Expression contains only one element, and it is the name of a macro,
the macro's definition is examined. If the definition is a number (integer or
floating-point, positive or negative), then this becomes the value of the
expression. If the definition starts with ' (apostrophe), then the quoted
word or string is the value of the expression (explained in
Section 9.8).
Otherwise, the macro is assumed to be composed of Kermit commands (possibly
including S-Expressions), which are executed. If the macro has a RETURN
value, or it executes an S-Expression as its last command, the result becomes
the value of the S-Expression; otherwise the result is empty.

For S-Expressions that contain more than one element, and the first element is
the name of a macro, then this macro is executed with the arguments that are
given, after the arguments are evaluated by the S-Expression reader.
Likewise, If the first element is a built-in operator, then it is applied to
the operands after they are evaluated. In both cases, each operand is fed to
the S-Expression reader recursively for evaluation. If an operand is a number
or a quoted string, it is used as-is. But if it's a macro name, this
degenerates into the first case, and the previous paragraph applies.

The assignment operators SETQ and LET apply to global and local variables,
respectively. SETQ and LET are standard Lisp operators adapted to Kermit
scoping rules. When the operands are numeric or arithmetic, SETQ is
equivalent to Kermit's EVALUATE command:

(setq a (+ 1 2))
evaluate a 1 + 2

When the operand is a string, SETQ is equivalent to DEFINE:

(setq a '(this is a string))
define a this is a string

In the first case, both statements create a macro named "a" with a value of 3.
But in neither case is the macro "a" necessarily global. If either of these
commands executes in an environment (i.e. macro invocation level) where a
"local a" command has been given, the "a" macro is global to that environment,
but is not visible outside it.

LET is equivalent to the Kermit LOCAL command, followed by the corresponding
EVALUATE:

(let a (+ 1 2))

is equivalent to:

local a
evaluate a 1 + 2

Again, "local" in this context applies to the Kermit macro invocation stack,
not to the S-Expression nesting level. To illustrate, recall our "newarea"
macro:

In both cases, the variables a, b, c, and s are local to the "newarea" macro,
and global within it.

Multiple assignments can be handled in several ways. Here is the obvious way
to initialize a series of variables to the same value:

(setq a 0)
(setq b 0)
(setq c 0)
(setq s 0)

Here is a more compact and efficient way of doing the same thing:

(setq a 0 b 0 c 0 s 0)

However, in case the value was more complex, it's better to put only one copy
of it in the S-Expression; in this case we rely on the fact that SETQ returns
the value of its last assignment:

(setq a (setq b (setq c (setq s (* x (^ y 2))))))

Similarly, to set a series of variables to x, x+1, x+2, ...

(setq c (+ (setq b (+ (setq a (+ (setq s x) 1)) 1)) 1))

In the last example, you can see why "last" does not always correspond to
"rightmost" (the leftmost variable "c" is assigned last).

If you are working with backslash variables like \%a or array elements
like \&a[1], remember two rules:

Don't put spaces inside array brackets.

You must double the backslash when using SETQ, LET, ++, or
-- to assign a value to a backslash variable.

Examples of assigning to a backslash variable:

(setq x 1)
(setq \\%a 0)
(setq \\&a[x+1] 1)
(++ \\%x)
(-- \\&a[x+2])

Examples of referring to a backslash variable's value:

(setq a (+ \%a 1))
(setq b (+ \%a \&a[1]))
(++ a \%x)
(-- b \&a[1])

The special notation is required because all backslashed items
(\%x variables,
array elements, built-in
\v(xxx) variables, and
\fxxx() function invocations)
are evaluated in a single pass BEFORE the S-Expression is executed; any other
approach would result in unacceptable performance. So, for example, in:

The IF operator provides a compact form of decision-making within
S-Expressions. An IF expression can stand wherever a number might stand, as
long is it returns a number. Here's a quick way to obtain the average value
of all the elements in an array that contains only numbers:

(/ (+ \fjoin(&a)) (float \fdim(&a)))

This results in a "Divide by zero" error if the array is empty. If you want
to define the average value of an empty array to be 0 instead of getting an
error, you can use IF to check the array size:

and the "then" and "else" parts can contain multiple S-Expressions enclosed
within (EVAL ...):

(if x (eval (...) (...) (...)) (eval (...) (...) (...)))

AND and OR operators are guaranteed to "short circuit". If any operand of AND
is false, none of the subsequent operands is evaluated; likewise, if an OR
operand is true, no further operands are evaluated.

Bear in mind that the S-Expression IF is not the same as Kermit IF; the
condition is only allowed to be an S-Expression or a variable or number, not
the whole list of possibilities you see when you type "if ?" at the
C-Kermit>
prompt. But keep reading...

To extend the capabilities of S-Expressions, you can use Kermit macro names
as operators, with the following limitations:

The macro must not have the same name as a built-in operator.

You must use the full macro name, not an abbreviation.

And with the following enhancement:

If the last statement executed by the macro is an S-Expression, its value
is returned automatically. In other words:

define bump (++ \%1)

is equivalent to:

define bump return \fsexpression(++ \%1)

Here's an example in which we define a FIBONACCI operator that returns the
nth element, n >= 0, of the Fibonacci series, 0 1 1 2 3 5 8
13 21 34 55, . . ., in which the first element is 0, the second is 1, and each
subsequent element is the sum of the two before it. This series was devised
by Leonardo Pisano, Filius Bonacci (Fibonacci for short) in 1202 to describe
how fast rabbits can breed, and also forms the basis for the Golden Mean, the
branching behavior of plants, the spiral of a nautilus shell, etc.
(Thanks to Dat Thuc Nguyen
for December 2003 corrections to this section!)

We can write a FIBONACCI function as a macro easily with S-Expressions:

Recall that "END nonzero-number [ message ]" causes a macro
invocation to fail. When the macro is the operator in an S-Expression, this
makes the S-Expression fail too. Also note that our Fibonacci macro is just
an illustration, not a practical example. Since it is recursive (calls
itself), it won't work for large arguments because the call stack can exceed
available memory. See Section 9.9.2 for a practical
alternative.

Kermit macros, when used as S-Expression operators, can do anything at all
except initiate file transfers: they can print messages on the screen, read
and write files, interact with the user, and so on. For example, here's a
macro ASKME that asks you to enter a number, makes sure that you did, and then
returns its value for use in the S-Expression:

To send string parameters to a macro, some kind of quoting is required to tell
the S-Expression parser to take a given "word" literally rather than replacing
it by its value. For this we use the Lisp QUOTE operator:

This causes the string "abcdefghijklmnopqrstuvwxyz" to be sent literally to
the LENGTH macro. Kermit, like Lisp, also offers a shortcut for QUOTE, that
lets us quote a word by prefixing it with a single quote (')
character, also called apostrophe (ASCII 39):

(length 'abcdefghijklmnopqrstuvwxyz)
26

The two forms are equivalent.

How the macro treats its arguments is up to the macro. In the example above,
the argument is treated as a literal string. However, it can also be treated
as a variable name:

Note the construct \m(\%1). This means "the value of the macro whose
name is the value of \%1". The value of \%1 in this case
is the word "string", and the value of the macro whose name is "string" is
"This is a string".

What if the macro takes multiple arguments, or a variable number of them?
Here's a simple macro that prints a phrase that includes its arguments:

Since the COMPLAIN macro uses \%* to refer to all its arguments, no
matter how many, it doesn't care which form you use. But it makes a
difference in cases where the macro refers to its arguments individually.

To illustrate, let's consider a macro that receives the name of a macro and
its argument list and executes it with its arguments, without knowing how many
arguments there are. The following LOOP macro is used to execute the given
macro with the given argument list the requested number of times:

def loop { local i, for i 1 \%1 1 do \%2 \%3 }

Within the LOOP macro, the first argument (\%1) is the loop count,
\%2 is the macro name, and \%3 is the argument list. When
the LOOP macro is invoked traditionally like this:

loop 3 complain hot

it prints "It's too hot!" three times. To invoke it from an S-Expression,
you must quote both the macro name as well as the argument, since in this
case the macro name itself is an argument:

(loop 3 'complain 'hot)

Now what if you need to send different or variable numbers of arguments to the
LOOP macro? The LOOP macro can handle it already, provided you group the
arguments into LOOP's third argument (\%3). In Kermit syntax, without
grouping:

loop 3 complain cold and wet

prints "It's too cold!" three times ("and wet" is lost); but with grouping
(either of the following two forms):

loop 3 complain {cold and wet}
loop 3 complain "cold and wet"

the LOOP macro prints "It's too cold and wet!" three times as desired.

To do the same thing in an S-Expression, just use the Lisp forms of quoting
instead of the Kermit forms; the following two are equivalent:

(Recall that \&_[] is the macro's argument vector array,
equivalent to \%1, \%2, ...) The DISPLAY macro can be used
in S-Expressions like this:

(setq a 1 b 2 c 3)
(display 'a 'b 'c 'd)

which prints:

a = 1
b = 2
c = 3
d =

The names must be quoted to prevent their evaluation before they are sent to
the macro. This ability to pass variables "by name" to macros, rather than by
value, lets you write macros that change the values of argument variables.
For example, here's a macro that doubles the value of its argument variable:

define double (++ \%1 \%1)

which you can call like this:

(setq a 12)
(double 'a)

In the macro, \%1 is replace by the variable name "a";
"(++ a a)" adds "a"
to itself, and sets the value of "a" to the result.

There are no built-in operators other than QUOTE, ', and STRING for
handling strings in S-Expressions, but using just these, plus macros that use
Kermit's regular string-handling features, you can easily extend S-Expressions
to do string manipulation:

The two are exactly equivalent. In both cases, the macro "foo" has the
value:

'(this is a string)

so when it is retrieved it can be identified as a string rather than a
number or commands to be executed. Thus:

(setq foo (quote (this is a string)))
show macro foo
foo = '(this is a string)
(foo)
this is a string

Note the different results for "showmacrofoo" and
"(foo)". The former shows the internal definition; the latter
evaluates the variable, which removes the quoting. And perhaps more
important, note that if the apostrophe and surrounding parentheses were not
stored as part of the definition, (foo) would try to execute "this is
a string" as a command.

Note that, unlike built-in S-Expression operators that return numbers or truth
values, these operators return strings. If you want to assign their return
values to other variables, you can do so:

(setq bar (rev (cap foo))) Result: GNIRTS A SI SIHT

But now the S-Expression processor doesn't know the value of "bar" is supposed
to be a string, rather than a macro to execute. For this you need one final
special operator, STRING. The STRING operator takes an S-Expression as an
operand, evaluates it, and then returns its value enclosed in '(), so
you can use the value as a string is subsequent S-Expressions. Use STRING for
referencing macros that return strings:

(setq bar (string (rev (cap foo)))) Result: '(GNIRTS A SI SIHT)

STRING is like QUOTE, except that it evaluates its operand before applying
the quoting, rather than taking the operand literally.

To reference backslash variables or functions that return string values,
you must use the regular quoting mechanisms:

That's because backslash items are evaluated BEFORE the S-Expression parser
ever sees them, and the values of \v(time) and so on are not valid
S-Expressions, so STRING won't like them.

Finally a brief word on the touchy topic of quoting. Suppose you want to
include (say) literal parentheses in a string that will later be processed by
the S-Expression reader (or \fsplit() or \fword()).
Normally, you can't do this because parentheses are meaningful in these
contexts. To defeat the normal parsing rules, you can quote the parentheses
with backslash. However, due to the many levels of string processing
involved, a surprisingly large amount of backslashes might be required, for
example:

This is nearly impossible to explain(*). Instead, just remember two points:

In situations like this, it's better to use DEFINE to create the string,
rather than SETQ. The example above requires only double backslashes
when DEFINE is used:

define s '(a b (c d) \\(e f (g h) x\\) j k)

The level of quoting depends on how many levels of evaluation the string
must pass through, which is not always obvious. However, the number of
backslashes required in any given situation is always a power of 2. So
if 1 doesn't work, try 2; if 2 doesn't work, try 4; if 4 doesn't work,
try 8, 16, 32, and so on.

Considerations like this apply in any scripting language (shell, Tcl, Perl,
Python, etc). The situation is known as "Quoting Hell".

(*) If you really want an explanation, here it is:

Every SEXP has its backslash items evaluated in a single pass at top
level before being passed to the SEXP reader, so \%1,
\v(ftime), etc, can
be evaluated up front, freeing the SEXP reader of having to know about
such things, which in turn makes it much more efficient. Therefore one
level of quoting is lost right away, and therefore you must double each
backslash that is to be used as a quote.

When the SEXP reader sees '\', it treats it as a quote; discards
it and keeps the next character. Thus '\\' becomes '\'.
This would be the end of it, except that:

The SEXP reader must call itself recursively on its operands, so we must
double any quotes in the operands: 2^2 = 4.

If the result is to be passed as an argument to a macro, the backslashes
must again be doubled, because the macro processor evaluates the arguments
before sending them to the macro: 2^3 = 8.

If the macro itself is to see the quotes, rather than just the result of
the quoting, the quotes must be doubled again: 2^4 = 16.

Moral: To create string constants in which grouping characters must be quoted,
use DEFINE rather than SETQ.

The following program computes statistics -- means, maxima, minima, variance,
standard deviation, and correlation -- from data stored in parallel arrays,
\&x[] and \&y[], which can contain any mixture of
integer and floating-point numbers: positive, negative, or zero. Array setup
and validation are not shown. Except for the traditional FOR loop and
printing the results at the end, the entire computation is done with
S-Expressions:

The final "if tmp" check accounts for the possibility that both arrays contain
all 0's. Results can also be printed with "echo CC = \m(cc)", or any
other desired way. Interestingly, if we had not needed the sum of the squares
and products, we could have obtained the sums, maxima, and minima of the X's
and Y's without a loop like this:

The recursive Fibonacci example given previously is simple and elegant, but
not very useful since it causes memory occupation to grow each time it calls
itself, until eventually both physical memory and disk swap space are filled
and the program crashes. Even for small arguments, like 17, execution time
can be prohibitive:

Algebraic notation uses infix operators and normal rules of operator
precedence, with parentheses used to force exceptions to the rules; many
operations can be included in an expression. S-Expressions use prefix
operators with no intrinsic precedence; each operation is enclosed in
parentheses, and the arrangement of parentheses determines precedence.

Algebraic infix operators require two operands; S-Expression prefix
operators can accept a variable number of operands.

You can use algebraic notation anywhere that C-Kermit accepts a number,
e.g. "echo\&a[((1+1)*2-1]", but you can use
S-Expressions only as top-level commands. You can, however, use either
algebraic or S-Expressions anywhere at all by enclosing them in
\fevaluate() or \fsexpression(), respectively.

You can use any mixture of integer and floating-point numbers in
S-Expressions, but only integers are permitted in algebraic expressions.
Outside of S-Expressions, floating point arithmetic is supported only
by \ffp...() function calls.

Operators and operands in S-Expressions must be separated by spaces,
e.g. "(+ a b)". Spaces are not required in algebraic expressions:
"((a+b)*c)".

When assigning values to backslash variables (such as \%x or
\&a[2]) using SETQ or LET, you must double the backslash.

Most dialects of real Lisp do not allow S-Expressions that don't start
with an operator, for example:

(a)

This expression can cause an error in Lisp (even if "a" has a value),
but is acceptable in Kermit, where it returns the value of the variable
"a". Similarly, (1) returns the value "1".

In real Lisp, EVAL requires exactly one operand. In Kermit, it can
have 0, 1, 2, or more operands. It returns the value of the last operand
evaluated.

Real Lisp SETQ and LET usually require an even number of operands.
Kermit allows an odd number, in which case the last (or only) variable
is undefined (i.e. deleted, destroyed).

Kermit does not support ratios such as "7/8". Some Lisp dialects accept
ratios as numbers, and generate ratios when told to divide two integers
whose quotient is not a whole number; e.g. in Common Lisp:

[13] USER(37): (/ (+ 1 2 3 4) 3)
10/3
[13] USER(38):

The result of (/ 10 3) is 3.333.... Some Lisp dialects truncate
the result to 3 since both operands are integers, some don't; some give the
result as a ratio. C-Kermit always gives a floating point result when
there is a fractional part. If you want an integer result, you can use
TRUNCATE, FLOOR, or CEILING, e.g. (truncate (/ 10 3)).

There is currently no "bignum" support. Large numbers can be used and
large results generated, but (as noted in Section 9.2)
they are accurate only to the precision of the underlying machine.
\v(math_precision) gives the machine precision as a number of decimal
digits, e.g. 16.

Scientific notation for floating-point numbers is not supported. If the
magnitude of a number is greater than the precision of the underlying
hardware, the less-significant digits are shown but their values are
meaningless. If it the number is too small to be represented
internally, it is shown as "0.0".

Many Lisp features are omitted: List processing (CAR, CDR, etc),
DEFUN, Lisp-specific control structures, and so on.

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

When sending commands to a Kermit server, this tells whether command
packets should be preceded by an I (information) packet, which is used
to synchronize parameters prior to executing the command. Normally ON.
The only reason to set this OFF is for communicating with buggy Kermit
servers that misbehave when an I packet is sent to them. There is also
a SET RECEIVE I-PACKETS command, but presently it has no effect.

SET TRANSFER MESSAGE[ text ]

Sets an initial message to be shown in the Last Message field of the
fullscreen file-transfer display.

In C-Kermit 8.0, the default modem type for dialing has changed from
NONE (= DIRECT, meaning no modem) to GENERIC. This change should have no
impact on direct connections. For dialing, it means that, unless you
SET MODEM TYPE to a specific type, such as USROBOTICS or CONEXANT, Kermit
assumes:

The modem uses the Hayes AT command set.

The modem supports error correction, data compression, and
hardware flow control and is already configured to use them.

In fact, Kermit assumes the modem is completely configured, and therefore
does not send it an initialization string or any configuration commands.
Instead, it sends only the simplest and most portable commands:

ATQ0V1 Give dial result codes. ATDTnumberDial the number.

(or ATD or ATDP, as appropriate).

The new defaults work for direct connections and for most modern modems on
most platforms, and they work much faster than "full-treatment" dialing. If
the new defaults don't work for you, or if you need to perform explicit modem
configurations or interactions, then set a specific modem type and use the SET
MODEM and SET DIAL commands as documented in Using C-Kermit.

WARNING: Don't use the generic modem on hosts that do not support
RTS/CTS flow control. If Xon/Xoff is in use on the serial port, you'll need
to select a particular modem type so Kermit knows what command to give it
to enable Xon/Xoff flow control between itself and your serial port.

Added in C-Kermit 8.0.201: Rudimentary support for
Caller ID, for use with the ANSWER command. If the modem reports
Caller ID information, Kermit stores it in variables that you can access after
the call is answered:

\v(callid_date) The date of the call
\v(callid_time) The time of the call
\v(callid_name) The name of the caller
\v(callid_nmbr) The telephone number of the caller
\v(callid_mesg) A message

The format of these items depends on the originating and answering phone
companies and the modems and their configuration.

Not very many modems support Caller ID, and those that do (a) tend to have
it disabled by default, and (b) use different commands to enable it. A
quick survey shows of some current models shows:

To use Kermit's Caller ID feature, you have to set the modem to wait for
at least two rings before answering, and you have to give the command to
enable Caller ID; for example (after choosing a modem with SET MODEM TYPE):

set modem command autoanswer on ATS0=2#CID=1\{13}
set modem command autoanswer on ATS0=2+VCID=1\{13}

These commands can be undone with:

set modem command autoanswer on ATS0=1#CID=0\{13}
set modem command autoanswer on ATS0=1+VCID=0\{13}

Kermit presently has no built-in knowledge of the Caller ID capabilities
or commands of the modems in its database.

Since the variables can be accessed only after the call is answered, the
only way to refuse a call is to answer it, inspect the variables, and then
hang it up if desired.

Now that 7-bit connections are no longer the norm, the default terminal
bytesize (also called "data size" or "word size") in C-Kermit 8.0 is 8 bits,
rather than 7 bits as it was in C-Kermit 7.0 and earlier:

This command, which specifies your CONNECT-mode escape character, allows
you to specify any ASCII control character in a variety of formats. C-Kermit
8.0.201 now also lets you specify any 8-bit value, 128-255, as the escape
character. In the SET ESCAPE command, you can type the 8-bit character
literally or you can enter its numeric code. Here are examples that you
can enter from a terminal or console that uses the ISO Latin-1 character set:

Both of these commands set the escape character value to 195 (decimal), which
happens to be uppercase letter A with Tilde in Latin-1. SHOW ESCAPE and
SHOW TERMINAL show the value, as does the CONNECT message.

SET TERMINAL AUTODOWNLOAD ERROR{STOP, CONTINUE}

When Kermit has a terminal connection to another computer, and a file
transfer is initiated automatically because a Kermit packet was received in
CONNECT mode (i.e. in the terminal screen), this command tells what Kermit
should do if the transfer fails. The default is to STOP, which leaves Kermit
in command mode with its file-transfer display showing, so you can see that
the transfer failed and why. If you SET TERMINAL AUTODOWNLOAD ERROR CONTINUE,
this causes Kermit to return automatically to its terminal screen (i.e. resume
its CONNECT session) as if the transfer had succeeded; this can be desirable
if the entire session is under control of a host-based script.

SET TERMINAL BYTESIZE{7, 8}

The byte size to use during CONNECT and INPUT command execution, which
can be more restrictive than the bytesize implied by the current PARITY
setting, but not less restrictive. In C-Kermit 7.0 and earlier,
the terminal bytesize was 7 by default to protect against the likelihood
that parity was in use on the connection without the user's knowledge. When
the terminal bytesize is 8 (as it is in C-Kermit 8.0 and later), the user
will see garbage in this (increasingly unlikely) situation. Note that 8 data
bits are required for most character sets other than ASCII: Latin-1, UTF-8,
and so on.

A new command has been added to produce timestamped session logs:

SET TERMINAL SESSION-LOG TIMESTAMPED-TEXT

Records the terminal session in text mode (like
SET TERMINAL SESSION-LOG TEXT) but adds a timestamp at the beginning of
each line. The timestamp format is
hh:mm:ss.nnn,
and indicates the time at which the first character of the line appeared.

In most UNIX versions (those built with the select()-capable CONNECT
module -- pretty much all the ones that have or could have TELNET included),
an idle timeout feature has been added:

SET TERMINAL IDLE-TIMEOUTnumber

If the number is not 0, then Kermit is to take an action when the given
amount of time passes with no activity during CONNECT mode. If the number is
positive it is the maximum number of idle seconds; if number is negative it
represents milliseconds (thousandths of seconds). If 0 is given as the
number, there are no idle timeouts. Synonym: SET TERMINAL
IDLE-LIMIT.

SET TERMINAL IDLE-ACTION{RETURN, HANGUP, EXIT, OUTPUT[ string ] }

The action to be taken upon an idle timeout in CONNECT mode.
RETURN to the prompt, HANGUP the connection, EXIT from Kermit, or OUTPUT
the given string (if no string is given, a NUL (ASCII 0) character is sent).

SET TERMINAL IDLE-ACTION{TELNET-NOP, TELNET-AYT }

Actions that can be selected on Telnet connections only, that might be
useful if idle limits are enforced by the Telnet server or in the TCP/IP
protocol: TELNET-NOP sends a "NO Operation" (do-nothing) command, which causes
no response from the server; TELNET-AYT sends an "Are You There" message to
the server, which should make the server send back a message. Neither of
these actions interferes with your remote session.

SET TERMINAL IDLE-ACTION is useful for connections to hosts or services
that automatically log you out after a certain amount of idle time, e.g.:

set term idle-timeout 300
set term idle-action output \32

sends a space (as if you had pressed the space bar) every 300 seconds (five
minutes) while there is no activity (32 is the ASCII code for space).

When C-Kermit returns from CONNECT to command mode, the reason for the
transition is given in a new variable, \v(cx_status):

For years, C-Kermit has supported dialing out from Telnet modem servers (also
called reverse terminal servers or access servers), but until now there was no
way for Kermit to control the communication parameters (speed, parity, etc) on
the serial port of the terminal server; it had to use whatever was there.

But now, if you make a connection to a server that supports the Telnet Com
Port Control Option,
RFC 2217, you have the
same degree of control as you would have over a serial port on the computer
where Kermit is running: SET SPEED, SET FLOW, SET PARITY, SET STOP-BITS, SHOW
COMM, WAIT, SET CARRIER-WATCH, the modem-signal variables, sending Break, and
so on, apply to the connection between the terminal server and the modem.

For example, using a Cisco Access Server 2509, where specifying a TCP port in
the 6000's selects a serial port that can be used for dialing out:

set host xxx 6001 ; xxx is the IP hostname or address of the server
(log in if necessary) ; With a script or by hand
set modem type usr ; Tell Kermit what kind of modem it has
set speed 57600 ; This affects the server's port
set flow rts/cts ; Ditto
dial 7654321

The modem server might or might not require a login sequence. It might also
allow for automatic authentication, e.g. via Kerberos tickets. NOTE: If the
modem server requires a login sequence, then REDIAL might not work as expected.

When you have a Telnet Com Port connection, your SET SPEED and SET FLOW
options change automatically to reflect the capabilities of the server, rather
than those of your local computer.

See the configuration manual for your server for additional information. For
example, how to set up the server to drop the Telnet connection automatically
when the telephone call is hung up (e.g. "autohangup" on Cisco models).

There are lots of faulty Kermit protocol implementations out there, found
mainly in 3rd-party products ranging from communications software packages
to file-transfer functions embedded within devices. This topic is covered
HERE for C-Kermit 7.0, but C-Kermit 8.0
adds some additional tricks.

SET ATTRIBUTE RECORD-FORMAT{ON, OFF}

Allows control of the Kermit's Record-Format attribute. Set this to
OFF in case incoming file are refused due to unknown or invalid record formats
if you want to accept the file anyway.

SET ATTRIBUTES OFF

This is not a new trick, but it was recently discovered that the Kermit
implementation embedded within a certain kind of punching/bending machine
(Salvagnini if you must know) hangs upon reception of standard format Kermit
attributes when receiving files. When sending files, it sends attributes of
its own, one per A-packet, which is slightly unusual but legal. When
receiving files from C-Kermit, K95, MS-DOS Kermit, Kermit-370, etc, it
simply exits upon reception of the first A-packet; apparently it was not
coded according to the protocol specification, which allows multiple
attributes per A-packet. Solution: tell the file sender to SET ATTRIBUTES
OFF.

SET SEND I-PACKETS{ON, OFF}

A Kermit server is supposed to accept I-packets; this is how the client
lets the server know its capabilities and preferences before sending a
command. Apparently there is at least one Kermit server implementation that
does not accept I-packets, and does not properly respond with an Error packet
if it gets one. To get around such situations in C-Kermit 8.0, you can use
SET SEND I-PACKETS OFF to inhibit the sending of I packets. In this case, the
client must be able to adjust to the server's configuration, rather than the
other way around as we are used to.

SET PROTOCOL KERMIT {} {} {}

C-Kermit 6.0 and later automatically send "autoupload" and "autodownload"
commands when in local mode and you give a file transfer command. For
example, if you tell kermit to "send oofa.txt", Kermit sends
"kermit -r" and a carriage return, in case you had forgotten to start Kermit
on the far end and told it to receive a file. If a Kermit program had already
been started on the far end, it should harmlessly absorb this string. However,
some Kermit programs violate the Kermit protocol definition and treat such
strings as Kermit packets even though they are not. In such cases, give
this command to set the Kermit protocol autoupload and download strings to
nothing, which tells Kermit not to send them. (This is not a new feature,
but it was not previously included in the "Coping" section of the
documentation.)

Kermit now accepts a selection of URLs (Universal Resource Locators) as its
first command-line argument. These are:

telnet:hostname

Makes a Telnet connection to the given host (IP hostname or address).

ftp://[user[:password]@]hostname[/path...]

Makes an FTP connection to the given host (IP hostname or address).
If a username is given, Kermit tries to log you in; if a password is given,
it is used; if not, you are prompted for one. If no username is given,
an anonymous login is performed. If a pathname is included, Kermit tries
to GET the given file. See Section 3.1.3 for details.

In C-Kermit 8.0, we make an effort to keep passwords out of the debug log.
This can never be 100% effective, but it's better than before, when there
were no precautions at all. Whenever Kermit knows it's prompting for,
parsing, or transmitting a password, it temporarily turns off logging and then
turns it back on afterwards. This keeps the debug log password-free in most
common cases, but there can be no guarantees.

There have been requests for other kinds of logs, for example a command log.
These might be added at some point. One person wanted to be able to log
commands with timestamps, but only commands issued at the prompt, not commands
from files or macros, and also wanted a header line at the beginning showing
the date, user, and host. This can be done as follows: