CKERMIT.BWR          "Beware File" for C-Kermit Version 6.0        -*- text -*-

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

Authors: Frank da Cruz and Christine M. Gianone, Columbia University.

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

Report problems, suggestions, fixes, etc, to:

  The Kermit Project
  Columbia University
  612 West 115th Street
  New York NY 10025-7799
  USA
  Email: kermit-support@columbia.edu
  Web:   http://www.columbia.edu/kermit/
  News:  comp.protocols.kermit.misc

C-Kermit 6.0 is documented in the book "Using C-Kermit" by Frank da Cruz and
Christine M. Gianone, Second Edition, 1997, Digital Press / Butterworth-
Heinemann, Woburn, MA, USA, ISBN 1-55558-164-1.  Price: US $41.95.  Available
in book and computer stores, or order by phone, call Columbia University at
+1 212 854-3703, or Butterworth-Heinemann at +1 800 366-2665.  A German edition
is available from Verlag Heinz Heise in Hannover, Germany.


WHAT IS IN THIS FILE

This is the "beware file" for C-Kermit.  It contains hints and tips,
frequently asked questions (and answers), troubleshooting advice, limitations
and restrictions, known bugs, etc, that apply to all C-Kermit variations.
This file is supplemented by a system-specific "beware file" for each major
system where C-Kermit runs:

  ckuker.bwr - All variations of UNIX: HP-UX, AIX, SCO, Solaris, etc.
  ckvker.bwr - Digital Equipment Corporation VMS and OpenVMS
  cklker.bwr - Stratus VOS
  ckdker.bwr - Data General AOS/VS
  ckmker.bwr - Apple Macintosh
  ckiker.bwr - Commodore Amiga
  cksker.bwr - Atari ST
  ck9ker.bwr - Microware OS-9
  ckpker.bwr - Bell Labs Plan 9

This file contains the following sections:

   (1) INCOMPATIBLE CHANGES IN VERSION 6.0
   (2) THE C-KERMIT COMMAND PARSER
   (3) MULTIPLE SESSIONS
   (4) NETWORK COMMUNICATION
   (5) THE SERVICES DIRECTORY
   (6) MODEMS AND DIALING
   (7) DIALING HINTS AND TIPS
   (8) TERMINAL SERVERS
   (9) TERMINAL EMULATION
  (10) KEY MAPPING
  (11) THE TRANSMIT COMMAND
  (12) FILE TRANSFER
  (13) SCRIPT PROGRAMMING


(1) INCOMPATIBLE CHANGES

These are not necessarily exhaustive lists.

The following incompatible changes were made in C-Kermit 6.0:

 . Unless you tell C-Kermit otherwise, if a serial or network connection
   seems to be open, and you attempt to EXIT or to SET LINE or SET HOST or
   TELNET, C-Kermit warns you that an active connection appears to be open
   and asks you if you really want to close it.  If you do not want these
   warnings, add SET EXIT WARNING OFF to your customization file.

 . The default for SET { SEND, RECEIVE } PATHNAMES was changed from ON
   to OFF, to prevent unexpected creation of directories and depositing of
   incoming files in places you might not know to look.

 . The default for SET FILE INCOMPLETE was changed from DISCARD to KEEP to
   allow for file transfer recovery.

 . The default file-transfer block-check is now 3, rather than 1.  If the
   other Kermit does not support this, the two will drop back to type 1
   automatically.

 . The default flow-control is now "auto" ("do the right thing"), not Xon/Xoff.

 . Backslash (\) is no longer a command continuation character.  Only -
   (hyphen, dash) may be used for this in C-Kermit 6.0 and later.

 . Negative INPUT timeout now results in infinite wait, rather than 1 second.

And in version 6.1:

 . The "multiline GET" command is gone.  Now use:

     get <remote-name> <local-name>

   or:

     get /as-name:<local-name> <remote-name>

   If either name contains spaces, enclose it in braces.

 . To request list of files from the server, you must now use MGET rather
   than GET:

      mget file1 file2 file3 ...

(2) THE C-KERMIT COMMAND PARSER

When using the command-line processor ("kermit -l /dev/tty00 -b 19200", etc),
note that in some cases the order of the command-line options makes a
difference, contrary to the expectation that order of command-line options
should not matter.  For example, the -b option must be given after the -l
option if it is to have any effect.

In the interactive command parser:

 . VMS-style command editing (arrow keys, etc) is not supported.
 . EMACS- or VI-style command line editing is not supported.
 . Editing keys are hardwired (Ctrl-U, Ctrl-W, etc).

If you interrupt C-Kermit before it has issued its first prompt, it will exit.
This means that you cannot interrupt execution of the initialization file, or
of an "application file" (file whose name is given as the first command-line
argument), or of an alternative initialization file ("-y filename"), and get
to the prompt.  There is, however, one exception to this rule: you *can*
interrupt commands -- including TAKE commands -- given in the '-C "command
list"' command-line argument and -- if there were no action commands among the
command-line arguments -- you will be returned to the C-Kermit prompt.  So,
for example, if you want to start C-Kermit in such a way that it executes a
command file before issuing its first prompt, and you also want to be able to
interrupt the command file and get to the prompt, include a TAKE command for
the desired command in the -C argument, for example:

   kermit -C "take dial.scr"

Reportedly, if you attempt to interrupt Kermit while it is executing its
initialization file, and you do this rapidly enough, e.g. by sending a
constant stream of Ctrl-C's at a very high rate, depending on the underlying
operating system (reported only on a couple versions of UNIX), duplicate
Kermit processes might be created -- cause unknown, cure unknown, workaround:
don't do it.

If you use the backslash (\) prefix to enter a control character, space, or
question mark into a command literally, the backslash disappears and is
replaced by the quoted character.  If it was a control character, it is shown
as a circumflex (^).  This allows editing (backspace, delete, Ctrl-W) to work
correctly even for control characters.

The only way to include a comma literally in a macro definition -- as opposed
to having it separate commands within the definition -- is to enter its ASCII
value (44) in backslash notation, e.g.:

  DEFINE ROWS MODE CO80\{44}\%1

If you quote special characters in a filename (e.g. in the SEND command),
filename completion may seem to work incorrectly.  For example, if you have a
file whose name is a*b (the name really contains an asterisk), and you type
"send a\\*<ESC>", the "b" will not appear, nor will Ctrl-R redisplay the
completed name correctly.  But internally the file name is recognized anyway.

Question-mark help does not work during execution of an ASKQ command.  The
question marks are simply accepted as text.

The maximum length for a variable name is 64 characters.  For array
declarations and references, that includes the subscript.

                                                     Sample
Some other maximums to watch out for:      Symbol    Value Defined in
							         
 Nesting level for command files:           MAXTAKE      30  ckuusr.h
 Nesting level for macros:                  MACLEVEL     50  ckuusr.h
 Nesting level for FOR / WHILE loops:       FORDEPTH     10  ckuusr.h
 Number of macros:                          MAC_MAX     256  ckuusr.h
 Size of INPUT buffer:                      INPBUFSIZ   256  ckuusr.h
 Maximum files to match a wildcard:         MAXWLD   varies  ck?fio.c
 Filespecs in MSEND command:                MSENDMAX    100  ckuusr.h
 Length of MSEND or GET string:             FSPECL      300  ckuusr.h
 Length for GOTO target label:              LBLSIZ       50  ckuusr.h
 Number of characters in a command:         CMDBL      1024  ckucmd.h
 Number of chars in a field of a command:   ATMBL       256  ckucmd.h
 \fexecute() recursion depth limit:         CMDDEP       20  ckucmd.h

The actual values of most of these items can vary with version and
configuration, and are listed by SHOW FEATURES.

ASK and ASKQ strip leading and trailing spaces from what the user types.  This
happens way down deep in the command parser -- it's nothing special about ASK
and friends.  The only way around this that works in both C-Kermit and MS-DOS
Kermit is for the user (the one who is responding to the ASK prompt) to type
(the first) leading space as "\32" and the (final) trailing space as "\32".
In this example, the password begins with 2 leading blanks and ends with two
trailing blanks, and "Passwd:" is the ASK prompt:

 Passwd:\32 secret \32

Of course, the user could also type *all* blanks as \32.

In OUTPUT commands only, \B and \\B send a BREAK signal, and \L and \\L send a
Long BREAK signal, and \N and \\N send a NUL (ASCII 0).  BREAK and Long BREAK
are special signals, not characters, and NUL is a character that normally
cannot be included in a C string, since it is the C string terminator.

If you really want to output a backslash followed by a B, an L, or an N (as is
needed to configure certain modems, etc), use "output \\B".

In C-Kermit 6.1 or later, you can disarm and re-arm the special OUTPUT-command
escapes (\B, \L, and \N) with SET OUTPUT SPECIAL-ESCAPES { OFF, ON }.

(3) MULTIPLE SESSIONS

C-Kermit does not support multiple sessions.  When you SET LINE (or SET PORT,
same thing) to a new device, or SET HOST to a new host, the previous SET LINE
device or network host connection is closed, resulting in hangup of the modem
or termination of the network connection.  In windowing environments like
HP-VUE, NeXTSTEP, OS/2, etc, you can run separate copies of Kermit in different
windows to achieve multiple sessions.

To achieve multiple sessions through a single serial port (e.g. when dialing
up), you can install SLIP or PPP on your computer and then use C-Kermit's
TCP/IP support over the SLIP or PPP connection, assuming you also have
TCP/IP networking installed on your computer.

On UNIX systems that support the "term" program, you can establish a
connection to another UNIX system with C-Kermit and then achieve multiple
sessions using "term" client programs like trsh (see ckuker.bwr and the term
documentation for details).


(4) NETWORK COMMUNICATION

In multiuser operating systems such as UNIX and VMS, TCP/IP RLOGIN connections
are available only to privileged users, since "login" is a privileged socket.
And assuming you are allowed to use it in the first place, it is likely to
behave differently depending on what type of host you are rlogging in to, due
to technical reasons having to do with conflicting interpretations of RFC793
(Out-Of-Band Data) and Rlogin (RFC1122)...  "Specifically, the TCP urgent
pointer in BSD points to the byte after the urgent data byte, and an
RFC-compliant TCP urgent pointer points to the urgent data byte. As a result,
if an application sends urgent data from a BSD-compatible implementation to an
RFC-1122 compatible implementation then the receiver will read the wrong
urgent data byte (it will read the byte located after the correct byte in the
data stream as the urgent data byte)."  Rlogin requires the use of OOB data
while Telnet does not.  Therefore, it is possible for Telnet to work between
all systems while BSD and System V TCP/IP implementation are almost always a
bad mix.

On a TCP/IP TELNET connection, you should normally have PARITY set to NONE and
(except in VMS C-Kermit) FLOW-CONTROL also set to NONE.  If file transfer does
not work with these settings (for example, because the remote TELNET server
only gives a 7-bit data path), use SET PARITY SPACE.  Do not use SET PARITY
MARK, EVEN, or ODD on a TELNET connection -- it interferes with TELNET
protocol.

If echoing does not work right after connecting to a network host or after
dialing through a TCP/IP modem server, it probably means that the TELNET
server on the far end of the connection is executing the TELNET protocol
incorrectly.  After initially connecting and discovering incorrect echoing
(characters are echoed twice, or not at all), escape back, give the
appropriate SET DUPLEX command (FULL or HALF), and then CONNECT again.
For a consistently misbehaving connection, you can automate this process in
a macro or TAKE file.

TELNET sessions are treated just like serial communications sessions as far as
"terminal bytesize" and "command bytesize" are concerned.  If you need to view
and/or enter 8-bit characters during a TELNET session, you must tell C-Kermit
to SET TERMINAL BYTESIZE 8, SET COMMAND BYTESIZE 8, and SET PARITY NONE.

If you SET TERMINAL DEBUG ON or SET DEBUG SESSION (same thing), TELNET
protocol negotiations will be displayed on your screen.  But most of the
interesting negotiations happen at the time the SET HOST or TELNET command
is given, before CONNECT mode is entered, so you won't see them on your
screen.  However, you can still capture them in the debug log ("log debug").

C-Kermit version 6.0 has a new set of SET TCP commands, to control TCP-level
parameters, such as "keepalive" protocol (that allows C-Kermit to detect
more quickly and reliably when a connection is broken).  Use SHOW NET to see
their values and SET TCP to change them.


(5) THE SERVICES DIRECTORY

Is now explained fully in "Using C-Kermit", 2nd Edition, Chapter 7.


(6) MODEMS AND DIALING

The list of modem types supported by C-Kermit is obtained by typing:

  set modem type ?

at the C-Kermit> prompt.  Note that the ITU-T (V.25bis) modem type is only
for asynchronous mode, not synchronous (HDLC) mode -- there is no support
in C-Kermit for synchronous communication (except for SET NET X.25, which
is only available on certain platforms).

Modems can be used by C-Kermit only when they are visible as or through a
regular serial port device.  Note that certain modems can not be used in this
normal way on many kinds of computers: Winmodems, RPI modems, Controllerless
modems, the IBM Mwave, etc; all of these require special drivers that perform
some, most, or all of the modem's functions in software.  Such drivers are
generally NOT available in UNIX or other non-Windows (or non-OS/2, in the case
of the Mwave) platforms.

An important change in C-Kermit 6.0 is that when you give a SET MODEM TYPE
command to tell Kermit what kind of modem you have, Kermit also sets a number
of other modem-related parameters automatically from its internal modem
database.  Thus, the order in which you give modem-related commands is
significant, whereas in prior releases they could be given in any order.

The new default for flow control is "auto", meaning "do the right thing".
So (for example) if your version of C-Kermit supports SET FLOW RTS/CTS and
your modem also supports RTS/CTS, then Kermit will automatically set its
flow control to RTS/CTS *and* set modem's flow control to RTS/CTS too before
attempting to use the modem.


(7) DIALING HINTS AND TIPS

Remember: In many C-Kermit implementations (depending on the underlying
operating system -- mostly Windows, OS/2, and System-V-based UNIX versions,
and in C-Kermit 6.1, also VMS), you can't CONNECT to a modem and type the
modem's dialing command (like "ATDT7654321") manually, unless you first tell
C-Kermit to:

  SET CARRIER-WATCH OFF

This is because (in these implementations), the CONNECT command requires the
modem's Carrier Detect (CD) signal to be on, but the CD signal doesn't come on
until after dialing is complete.  This requirement is what allows C-Kermit to
pop back to its prompt automatically when the connection is hung up.  See the
description of SET CARRIER-WATCH in "Using C-Kermit".

Similarly, if your dialed connection drops when CARRIER-WATCH is set to AUTO
or ON, you can't CONNECT back to the (now disconnected) screen to see what
might have happened unless you first SET CARRIER-WATCH OFF.

Don't SET FLOW RTS/CTS if your modem is turned off, or if it is not presenting
the CTS signal.  Otherwise, the serial device driver might get stuck waiting
for this signal to appear.

The HANGUP command has no effect when C-Kermit is in remote mode.  This is
on purpose.  If C-Kermit could hang up its own controlling terminal, this
would (a) most likely leave behind zombie processes, and (b) pose a security
risk.

Here are a few points to clarify the purpose of SET MODEM SPEED-MATCHING:

 0. The name was changed from SET DIAL SPEED-MATCHING to SET MODEM
    SPEED-MATCHING in edit 192, as part of the overhaul of the dialing
    features.

 1. This command does not do anything at all to the modem.  Rather, it is used
    to inform C-Kermit about the modem's configuration: whether the modem's
    interface speed is "fixed", or it changes its interface speed when a
    connection is made.  In the latter case, C-Kermit changes its own speed in
    response to the speed given in the modem's CONNECT message.  By default,
    SPEED-MATCHING is ON, so Kermit does indeed attempt to change its speed.
    If your modem is set to have a fixed interface speed, you must SET MODEM
    SPEED-MATCHING OFF.

 2. When MODEM SPEED-MATCHING is ON:

    (a) Your modem must be configured to report its *interface* speed in the
        CONNECT message, rather than the connection (modulation) speed.

    (b) Your computer (and C-Kermit) must support all connection speeds that
        might be reported by your modem.  SET SPEED ? will give you a list of
        the speeds that your version of C-Kermit knows about.

 3. If conditions (a) and (b) cannot be satisfied, then you must:

    (a) Configure your modem to lock its interface speed

    (b) Tell C-Kermit to SET MODEM SPEED-MATCHING OFF

To illustrate, suppose you have a V.32bis modem.  When it connects to a
remote V.32bis modem, it might issue a message like:

  CONNECT 14400

But 14400 bps is not a speed that is supported by certain operating systems
and so C-Kermit might fail to adjust its speed according to this report.
Therefore, you must lock the modem's interface speed at a higher speed (such
as 19200, 38400, or 57600) that is supported by C-Kermit, set C-Kermit to the
same speed, and tell C-Kermit to SET MODEM SPEED-MATCHING OFF.

If you have a high-speed, error-correcting, data-compressing, speed-buffering
modem, you should always SET MODEM SPEED-MATCHING OFF, and you should fix the
modem's interface speed as high as possible, preferably four times higher than
its maximum connection (modulation) speed to allow compression to work at full
advantage.  In this type of setup, you must also have an effective means of
flow control enabled between C-Kermit and the modem, preferably hardware
(RTS/CTS) flow control.

C-Kermit knows about a large number of modems, depending on how it was built
(type "set modem type ?" and "show features" for further info).  This
knowledge is imbedded in the SET MODEM and DIAL commands.  If you are having
trouble dialing your modem, SET DIAL DISPLAY ON to watch the dialing
interactions between C-Kermit and your modem.  Consult Chapters 3-4 of "Using
C-Kermit" (2nd Ed) for modem-dialing troubleshooting instructions.

If it takes your call longer to be completed than the timeout interval that
C-Kermit calculates, you can use the SET DIAL TIMEOUT command to override
C-Kermit's value.  But beware: the modem has its own timeout for completing
the call.  If it is a Hayes-like modem, C-Kermit adjusts the modem's value
too by setting register S7.  But the maximum value for S7 might be smaller
than the time you need!  In that case, C-Kermit sets S7 to 0, 255, or other
(modem-specific) value to signify "no timeout".

WARNING: Certain modems might have a maximum dial timeout shorter than what
Kermit expects it to be.  If Kermit attempts to set register S7 to a value
higher than your modem's maximum, the modem will say "ERROR" and you will get
a "Failure to initialize modem" error.  In that case, use SET DIAL TIMEOUT to
override C-Kermit's calculation of the timeout value with the highest value
that is legal for your modem, e.g. 60.

If you DIAL a modem, disconnect, then SET HOST or TELNET, and then HANGUP,
Kermit sends the modem's hangup command, such as "+++ATHO".  There is no good
way to avoid this, because this case can't reliably be distinguished from the
case in which the user does SET HOST <terminal-server>, SET MODEM TYPE <name>,
DIAL.  In both cases we have a valid modem type selected and we have a network
connection.  If you want to DIAL and then later make a regular network
connection, you will have to SET MODEM TYPE NONE or SET MODEM HANGUP RS232 to
avoid this phenomenon.

The SET MODEM KERMIT-SPOOF command works only for Telebit and US Robotics
modem types; it is OFF by default.  You may wish to experiment with large
packets (1K or greater) and various window sizes with spoofing disabled in the
modem.  In most situations the transfer rates achieved by Kermit with sliding
windows and long packets are better than with protocol spoofing turned on.
Also, attribute (A) packets are not passed by Telebit modems with spoofing
enabled so if they are desired spoofing must be turned off.

Some modems have a feature called adaptive dialing.  When they are told to
dial a number using Tone dialing, they check to make sure that dialtone has
gone away after dialing the first digit.  If it has not, the modem assumes the
phone line does not accept Tone dialing and so switches to Pulse.  When
dialing out from a PBX, there is almost always a secondary dialtone.
Typically you take the phone off-hook, get the PBX dialtone, dial "9" to get
an outside line, and then get the phone company's dialtone.  In a situation
like this, you need to tell the modem to expect the secondary dialtone.  On
Hayes and compatible modems, this is done by putting a "W" in the dial string
at the appropriate place.  For example, to dial 9 for an outside line, and
then 7654321, use ATDT9W7654321.  In Kermit 95, this is accomplished with:

  SET PBX-OUTSIDE-PREFIX 9W

(replace "9" with whatever your PBX's outside-line prefix is).

DEC modems...  Reportedly, these don't work right when connected to a DEC
terminal server -- result codes are never reported (on the other hand, this
might be a modem configuration problem).  Dialing "by hand", "blind" still
works.  Also, reportedly "For people who do have DEC modems directly connected
to DEC computers the DF03, DF100-series, and DF200-series modem dialers should
work.  The only thing that is not straightforward is that the DF124-CA,
DF124-CM modems must use the DF200-series since they speak Digital Modem
Command Language (DMCL) and AT commands.  The Digital Scholar Plus is a DF242
so it uses the DF200-series."

If C-Kermit's dialing methods are insufficient for your purposes, you can
write a C-Kermit script program to do the dialing.

(7.1) DIALING AND FLOW CONTROL

Most modern modems support RTS/CTS (if they support any hardware flow control
at all), but some computers use different RS-232 circuits for the same
purposes, e.g. DTR and CD, or DTR and CTS.  In such cases, you might be able
to make your computer work with your modem by appropriately cross-wiring the
circuits in the cable connector, for example the computer's DTR to the modem's
RTS, and modem's CD to the computer's CTS.  HOWEVER, C-Kermit does not know
you have done this.  So if you have (say) SET FLOW DTR/CD, C-Kermit will make
no attempt to tell the modem to use RTS/CTS.  You probably did this yourself
when you configured the modem.

(7.2) ESCAPE SEQUENCE GUARD TIME

A "TIES" (Time-Independent Escape Sequence) modem does not require any guard
time around its escape sequence.  The following text:

+++ATH0

if sent through a TIES modem, for example because you were uploading this
file through it, could pop the modem back into command mode and make it hang
up the connection.  Newer versions of the Telebit T1600 and T3000 (version
LA3.01E firmware and later), and all WorldBlazers, use TIES.

Although the probability of "+++" appearing in a Kermit packet is markedly
lower than with most other protocols (see the File Transfer section below), it
can still happen under certain circumstances.  It can also happen when using
C-Kermit's TRANSMIT command.  If you are using a Telebit TIES modem, you can
change the modem's escape sequence to an otherwise little-used control
character such as Ctrl-_ (Control-Underscore):

  AT S2=31

A sequence of three consecutive Ctrl-_ characters will not appear in a
Kermit packet unless you go to extraordinary lengths to defeat more than a few
of Kermit's built-in safety mechanisms.  And if you do this, then you should
also turn off the modem's escape-sequence recognition altogether:

  AT S48=0 S2=255

But when escape sequence recognition is turned off, "modem hangup"
(<pause>+++<pause>ATH0<CR>) will not work, so you should also be sure to SET
DIAL MODEM-HANGUP OFF.


(8) TERMINAL SERVERS

How to DIAL from a TCP/IP reverse terminal server (modem server):

 1. (only if necessary) SET TELNET ECHO REMOTE
 2. SET HOST <terminal-server-ip-name-or-address> [ <port> ]
 3. SET MODEM <modem-type>
 4. (only if necessary) SET DIAL HANGUP OFF
 5. DIAL <phone-number>

The order is important.

Watch out for terminal server's escape character -- usually a control
character such as Ctrl-Circumflex (Ctrl-^).  Don't unprefix it in Kermit !

Ciscos -- must often be told to "terminal download"...  Cisco ASM models don't
have hardware flow control in both directions.

Many terminal servers only give you a 7-bit connection, so if you can't make
it 8-bit, tell Kermit to "set parity space".

The following story, regarding trouble transferring 8-bit files through a
reverse terminal server, was contributed by an Annex terminal server user
(begin quote):

Using C-Kermit on an HP 9000 712/80 running the HP-UX 10.0 operating system.
The HP was connected to a Xylogics Annex MICRO-ELS-UX R7.1 8 port terminal
server via ethernet.  On the second port of the terminal server is an AT&T
Paradyne 3810 modem, which is connected to a telephone line.  There is a
program which runs on the HP to establish a Telnet connection between a serial
line on the Annex and a character special file on the HP (/dev file).  This is
an Annex specific program called rtelnet (reverse telnet) and is provided with
the terminal server software. The rtelnet utility runs on top of the
pseudo-terminal facility provided by UNIX.  It creates host-originiated
connections to devices attached ot Annex serial ports.  There are several
command line arguments to be specified with this program: the IP address of
the terminal server, the number of the port to attach to, and the name of the
pseudo-device to create.  In addition to these there are options to tell
rtelnet how to operate on the connect: -b requests negotiation for Telnet
binary mode, -d turns on socket-leve debugging, -f enables "connect on the
fly" mode, -r removes the device-name if it already exists, etc.  The most
important of these to be specified when using 8 data bits and no parity, as we
found out, was the -t option.  This creates a transparent TCP connection to
the terminal server.  Again, what we assumed to be happening was that the
rtelnet program encountered a character sequence special to itself and then
"eating" those kermit packets.  I think this is all of the information I can
give you on the configuration, short of the values associated with the port on
the terminal server.  If I can provide any other details, just let me know.
Thanks again for your help.

(end quote)


(9) TERMINAL EMULATION

Except for the Windows, OS/2, and Macintosh versions, C-Kermit does not
emulate any kind of terminal.  Rather, it acts more or less as a "transparent
pipe", passing the characters you type during a CONNECT session to the remote
host, and sending the characters received from the remote host to your screen.
Whatever is controlling your keyboard and screen provides the specific
terminal emulation: a real terminal, a PC running a terminal emulator, etc, or
(in the case of a self-contained workstation) your console driver, a terminal
window, xterm, etc.

There are several exceptions to the "transparent pipe" rule:

 - During a TELNET ("set host") session, C-Kermit itself executes the
   TELNET protocol and performs TELNET negotiations.  (But it does not
   perform TN3270 protocol or any other type of 3270 terminal emulation.)

 - If you have changed your keyboard mapping using SET KEY, C-Kermit replaces
   the characters you type with the characters or strings they are mapped to.

 - If you SET your TERMINAL CHARACTER-SET to anything but TRANSPARENT,
   C-Kermit translates your keystrokes (after applying any SET KEY
   definitions) before transmitting them, and translates received characters
   before showing them on your screen.

 - If your remote and/or local TERMINAL CHARACTER-SET is an ISO 646 7-bit
   national character set, such as German, French, Italian, Swedish, etc, or
   Short KOI used for Cyrillic, C-Kermit's CONNECT command automatically skips
   over ANSI escape sequences to avoid translating their characters.  Only
   ANSI/ISO standard (VT100/200/300-like) 7-bit escape sequence formats are
   supported for this purpose, no proprietary schemes like H-P, Televideo,
   Tektronix, etc.

 - If your version of C-Kermit includes SET TERMINAL APC command, then
   C-Kermit's CONNECT command will handle APC escape sequences if TERMINAL
   APC is not set to OFF (which is the default).

If you are running C-Kermit under a console driver, or in a terminal window,
that emulates the VT100, and use C-Kermit to log in to a VMS system, the
console driver or terminal window (not Kermit) is supposed to reply to the
"what are you?" query (ESC Z) from the VAX.  If it doesn't, and you can't make
it do so, then you can (a) live with the "unknown terminal" problem; (b) tell
VMS to SET TERMINAL/DEVICE=VT100; (c) program a key using SET KEY to send the
appropriate sequence and then punch the key at the right time; or (d) use the
VMSLOGIN macro that is defined in CKERMIT.INI to do this for you
automatically.

SET SESSION-LOG { TEXT, BINARY }, which is effective in UNIX and AOS/VS but
not other C-Kermit versions, removes CR, DEL, NUL, XON, and XOFF characters
("Using C-Kermit" neglects to mention that XON and XOFF are removed).  The
TEXT-mode setting is ineffective during SCRIPT command execution, as well as
on X.25 connections.


(10) KEY MAPPING

Except in the terminal-emulating versions, C-Kermit's key mapping facilities
are limited to normal "ASCII" keys, and cannot be used with function keys,
arrow keys, arcane key combinations, etc.  Since C-Kermit runs on such a wide
variety of hardware platforms (including, for example, more than 360 different
UNIX platforms), it is not possible for C-Kermit to support every conceivable
keyboard under every release of every UNIX (or VMS, or ...) product on every
different kind of computer possibly under all manner of different console
drivers.

In technical terms, C-Kermit uses the read() function to read keystrokes, and
read() returns a single byte (value 0 through 255).  C-Kermit's SET KEY
function applies to these single-byte codes.  "Extended function" keys, such
as F-keys, arrow keys, etc, usually return either a 2-byte "scan code" or else
a character string (such as an escape sequence like "ESC O p").  In both
cases, C-Kermit has no way to tell the difference between such multibyte key
values, and the corresponding series of single-byte key values.  This could
only be done by accessing the keyboard at a much lower level in a highly
system-dependent manner, probably requiring tens of thousands of lines of code
to support even a sampling of the most popular workstation / OS combinations.

However, most workstation console drivers (terminal emulation windows, etc)
include their own key-mapping facility.  For example, on an IBM RS/6000, the
AIXterm program (in whose window you would run C-Kermit) allows rebinding of
the F1-F12 keys to arbitrary strings.  The same might or might not be true of
DECterm windows, Sun "vttool" or "crttool" windows, etc.  Consult the
technical documentation for your workstation or emulator.

The SET KEY command (except in OS/2) does not allow a key definition to be
(or contain) the NUL (\0) character.


(11) THE TRANSMIT COMMAND

Session logging is inactive during the TRANSMIT command, even if you have
given a LOG SESSION command.


(12) FILE TRANSFER

If you have a multihop connection, with the interior nodes in CONNECT
mode (Kermit, Telnet, Rlogin, or any other), you can expect (a) file transfer
to be slower, and (b) the connection to be less transparent (to control
characters, perhaps to the 8th bit) than a more direct connection.

The recovery feature (RESEND command) that was added in edit 190 works only
for binary-mode transfers.  In order for this feature to be useful at all, the
default for SET FILE INCOMPLETE was changed from DISCARD to KEEP.  Otherwise
an interrupted transfer would leave no partial file behind unless you had
remembered to change the default.  But now you have to pay closer attention to
Kermit's messages to know whether a transfer succeeded or failed --
previously, if it failed, the file would not show up on the receiving end at
all; in edit 190 and later, you'll get a partial file which could easily be
mistaken for the complete file unless you change the default back to DISCARD
or read the screen messages, or keep a transaction log.

Watch out for SET FILE COLLISION RENAME, especially when used in conjunction
with recovery.  Recall that this option (which is NOT the default) renames
the incoming file if a file already exists with the same name (the default is
to rename the previously existing file, and store the incoming file with its
own name).  It is strongly recommended that you do not use SET FILE COLLISION
RENAME if you ever intend to use the recovery feature:

 . When the file is first received by C-Kermit, its name will be changed if
   another file already has the same name.  When you RESEND the same file
   after a failure, C-Kermit will probably try to append the re-sent portion
   to the wrong file.

 . Assuming that you get RESEND to work with FILE COLLISION RENAME, C-Kermit,
   when receiving the remainder of the file during a RESEND operation, will
   report back the wrong name.  Nothing can be done about this because the
   name is reported back before the receiving Kermit program finds out that
   it is a recovery operation.   

Automatic directory creation for received files does not work for pathnames
given in the "-a" command-line argument.

There are no command-line arguments for "set file names { literal, converted }"
or "set { send, receive } pathnames { on, off }", but you can include these
(or any other) commands on the command line in the -C option string.

When referring to MS-DOS, Windows, Atari ST, OS/2, or other file
specifications that contain backslash characters in a C-Kermit command, you
might have to double each backslash, for example:

  C-Kermit>get c:\\directory\\foo.txt

This is because backslash is used in C-Kermit commands for introducing special
character codes, variables, functions, etc.  If you are sending this GET
command to another copy of C-Kermit running as a server, for example on OS/2
or the Atari ST, it too treats backslashes as prefix characters, so you will
need 4 (yes, 4) copies of each backslash:

  C-Kermit>get c:\\\\directory\\\\foo.txt

But read about the new command, SET COMMAND QUOTING OFF, in the manual.

ANOTHER NOTE: In Kermit 95, this restriction is lifted as far as referring 
to files on the local PC.  You can now refer to these files using natural PC
notation, e.g.

  C-Kermit>send c:\letters\oofa.txt

Attempting to cancel local-mode file reception at a very early stage (i.e.
before data packets are exchanged) with X or Z does not work.  Workarounds:
Use E or Ctrl-C instead, or wait until the first data packets are sent.

If you cancel a transfer that is underway using X or Z, and a lot of window
slots are in use, it might take a long time for the cancellation to take
effect, especially if you do this on the receiving end; that's because a lot
of packets might already be on their way to you.  In that case, just be
patient and let Kermit "drain" them.

If C-Kermit is sending a file, remote-mode packet-mode breakout (Ctrl-C Ctrl-C
by default) is not effective until after C-Kermit sends its first packet.  If
C-Kermit is receiving a file or is in server mode, it will be effective right
away.  In the former case, the SET DELAY value determines the earliest time at
which you can break out of packet mode.

Some communication programs have errors in their implementation of Kermit
attribute packets.  If you get an error message from your communication
program like "Attribute error", tell C-Kermit to SET ATTRIBUTES OFF.  Better
yet, switch to a real Kermit program, such as MS-DOS Kermit.

When using C-Kermit to transfer files with the HP48SX calculator, you must
SET FLOW NONE.  The HP48SX does not support flow control, and evidently also
becomes confused if you attempt to use it.  You might also need to use
SET SEND PAUSE 100 (or other number).

The fullscreen file transfer display will not work right if your terminal type
is set incorrectly, or is not known to the host operating system.  Even when
it does work, it might slow down your file transfers a bit, especially on
high-speed network connections.  On certain small computers, it has been
reported to cause increased disk activity due to swapping or paging.  The
fullscreen display is not particularly useful with speaking or Braille devices.
In these cases, use SET FILE DISPLAY CRT or SET FILE DISPLAY SERIAL.

If you have trouble transferring files over a TCP/IP connection, give the
command:

  SET PARITY SPACE

and try again.  If that doesn't work, also try a shorter packet length.

On the other hand, if file transfers through a TCP/IP connection work, but are
very slow, use a longer packet length, 2000 or more, and also try increasing
the window size.  Also, make sure FLOW is NONE since TCP/IP handles flow
control itself, and XON/XOFF processing only slows things down.

Some communication software claims to implement sliding windows, but does so
incorrectly.  If sliding window transfers fail, set C-Kermit's window size to
the smallest one that works, for example:

  SET WINDOW 1

The UNIX version of C-Kermit discards carriage returns when receiving files
in text mode.  Thus, "bare" carriage returns (sometimes used to achieve
overstriking) are lost.

SET FILE COLLISION BACKUP is the default.  This means:

 - If you send the same file lots of times, there will be many backup files.
   There is no automatic mechanism within Kermit to delete them, no notion of
   a "version retention count", etc.

 - If a file arrives that has the same name as a directory, the file transfer
   fails.  Send the file with another name, or use SET FILE COLLISION RENAME.

 - If the directory lacks write permission, the file transfer fails even if
   you have write access to the file that is being backed up; in that case,
   switch to SET FILE COLLISION OVERWRITE or APPEND, or send to a different
   directory.

SET FILE COLLISION UPDATE depends on the date/time stamp in the attribute
packet.  However, this is recorded in local time, not GMT, and there is no
indication of time zone.  The time is expressed to the precision of 1 second,
but some file systems do not record with this precision -- for example, MS-DOS
records the file date/time only to the nearest 2 seconds.  This might cause
update operations to send more files than necessary.

SET FILE COLLISION OVERWRITE is risky, use it with caution.  Under certain
conditions, the existing file can be deleted even if the incoming file is
refused.

This paragraph does NOT apply to UNIX, where, as of C-Kermit 6.1, C-Kermit
pipes incoming mail and print material directly the mail or print program:
When C-Kermit is receiving files from another Kermit program that has been
given the MAIL or REMOTE PRINT command, C-Kermit follows the current filename
collision action.  This can be disconcerting if the action was (for example)
BACKUP, because the existing file will be renamed, and the new file will be
mailed (or printed) and then deleted.  Kermit cannot temporarily change to
RENAME because the file collision action occurs when the filename packet is
received, and the PRINT or MAIL disposition only comes later, in the Attribute
packet.

The STATISTICS command will produce an incorrect efficiency report if (a) it
does not know the true communication speed (e.g. on a network connection), or
(b) it knows the true serial interface speed to a modem, but the modem is
using a different communication speed with the other modem.  Similarly, in
these circumstances, C-Kermit's automatic calculation of the packet timeout
interval might also be incorrect, which can cause file transfers to fail.  One
solution to the latter problem is to SET SEND and RECEIVE TIMEOUT to
appropriate values for your true communication speed and packet length.

Execution of multiple file transfers by C-Kermit from a command file when
in remote mode might exhibit long delays between each transfer.  To avoid
this, just include the command "SET DELAY 0" in your command file before any
of the file-transfer commands.


(13) SCRIPT PROGRAMMING

13.1. Comments Versus the SCRIPT Command

Remember that ";" and "#" introduce comments when (a) they are the first
character on the line, or (b) they are preceded by at least one blank or
tab.  Thus constructions like:

  INPUT 5 ;
  SCRIPT ~0 #--#--# 

must be coded using backslash notation to keep the data from being ignored:

  INPUT 5 \59			; 59 is the decimal ASCII code for ";"
  SCRIPT ~0 \43--#--#		; 43 is the decimal ASCII code for "#"

or, more simply:

  INPUT 5 \;                    ; Just quote the semicolon
  SCRIPT ~0 \#--#--#            ; Just quote the "#"

13.2. Alphabetic Case and the INPUT Command

INPUT and REINPUT caseless string comparisons do not work for non-ASCII
(international) characters.  Workaround: SET INPUT CASE OBSERVE.  Even then,
the "lexically less than" and "lexically greater than" operations (IF LLT, IF
LGT) probably won't work as expected.  The same is true for the
case-conversion functions \Flower() and \Fupper().  C-Kermit does not know the
collating sequence for different character sets and languages.  (On the other
hand, it might work depending on such items as how Kermit was linked, whether
your operating supports "locales", etc)

13.3. NUL (0) Characters in C-Kermit Commands

You can't include a NUL character (\0) in C-Kermit command text without
terminating the character string in which it appears.  For example:

  echo In these brackets [\0] is a NUL

will echo "In these brackets [".  This applies to ECHO, INPUT, OUTPUT, and all
other commands (but you can represent NUL by "\N" in an OUTPUT string).  This
is because C-language strings are terminated internally by the NUL character,
and it allows all of C-Kermit's string comparison and manipulation functions
to work in the normal "C" way.

To illustrate:
  INPUT 5 \0
is equivalent to:
  INPUT 5
and:
  INPUT 5 ABC\0DEF
is equivalent to:
  INPUT 5 ABC

INPUT operations discard and ignore NUL characters that arrive from the
communication device, meaning that they do not figure into matching operations
(e.g. A<NUL>B matches AB); they are not deposited in the INPUT buffer
(\v(input)); and they are not counted in \v(incount), with two exceptions:

  1. An arriving NUL character restarts the INPUT SILENCE timer.

  2. An arriving NUL character terminates the INPUT command with the
     SUCCESS condition if the INPUT command was given an empty search
     string.  In this case \v(incount) is set to 1.

Also, the \v(inchar) variable is null (completely empty) if the last INPUT
character was NUL.  That is, there is no way to tell only by looking at
\v(inchar) the difference between a NUL that was INPUT and no INPUT at all.
If the INPUT command succeeded but \v(inchar) is empty, then a NUL character
was input.  Also, \v(incount) will be set to 1.

\v(incount) and \v(inchar) are NOT affected by the CLEAR command.

13.4. \ffiles() and \fnextfile() Peculiarities

The following script program:

  for \%i 1 \ffiles(oofa.*) 1 {
      send \fnextfile()
  }

does not work as expected in C-Kermit 6.0 and earlier.  The SEND command (and
any other command that parses a filename, including TAKE) implicitly calls the
same internal function that \ffiles() calls, and thus destroys the file list
set up in the first call to \ffiles(). In 6.1 and later, a separate list is
kept, so the following technique is not needed in the newer versions.

To work around the problem in C-Kermit 6.0 and earlier: (1) give the wild
filespec to \ffiles(); (2) loop through the file list and assign each filename
to an array element; (3) use the array of filenames in subsequent file-related
commands.  Example:

  asg \%n \ffiles(\%1)
  declare \&f[\%n]
  for \%i 1 \%n 1 { asg \&f[\%i] \fnextfile() }
  for \%i 1 \%n 1 {
      send \&f[\%i]
  }

13.5. Commands That Have Only Local Effect

Certain settings are local to each command level, meaning that subordinate
command levels (macros or command files) can change them without affecting
their values at higher command levels.  When a new command level is invoked,
the value is inherited from the previous level.  These settings are:

  CASE
  COUNT and \v(count)
  INPUT CASE
  INPUT TIMEOUT
  MACRO ERROR
  TAKE ERROR

This arrangement allows CASE, TIMEOUT, and ERROR settings, which are used to
control automatic exit from a command file or macro upon error, to be
automatically restored when the command file or macro exits.

The COUNT variable follows this rule too, which permits nested SET COUNT /
IF COUNT loops, as in this example in which the inner loop counts down from
the current COUNT value of the outer loop (try it):

  DEFINE INNER WHILE COUNT { WRITE SCREEN {   Inner:}, SHOW COUNT }
  SET COUNT 5
  WHILE COUNT { WRITE SCREEN Outer:, SHOW COUNT, DO INNER }

Keep in mind that an inferior command level cannot manipulate the COUNT
value held by a higher level.  For example:

  DEFINE OOFA SHOW COUNT, IF COUNT GOTO LOOP
  SET COUNT 5
  :LOOP
  OOFA
  ECHO Done

results in an infinite loop; the COUNT value remains at 5 because it is never
decremented at the same level at which it was set.

NOTE: "WHILE COUNT" did not work prior to edit 095 of ckuusr.c, 19 Jan 93.

13.6. Literal Braces in Function Calls

Since braces are used in function calls to indicate grouping, there is no way
to pass literal braces to the function itself.  Solution: Define a variable
containing the string that has braces.  Example:

  define \%a ab{cd
  echo \fsubstring(\%a)
  ab{cd  

If the string is to start with a leading brace and end with a closing brace,
then double braces must appear around the string (which itself is enclosed in
braces):

  define \%a {{{foo}}}
  echo \fsubstring(\%a)
  {foo}

This also works for any other kind of string:

  define \%a {{ab{cd}}
  echo \fsubstring(\%a)
  ab{cd  

13.7. Defining Variables on the C-Kermit Command Line

To define variables on the C-Kermit command line, use the -C command-line
option with one or more DEFINE or ASSIGN commands.  Note that the C-Kermit
command line must cope with the quoting rules of your shell.  Examples:

  kermit -C "define \\%a foo, define phonenumber 7654321"

In this case we follow UNIX quoting rules by doubling the backslash.  Once
C-Kermit starts, the \%a and \m(phonenumber) variables are defined as
indicated and can be used in the normal way.

In DOS or Windows or OS/2 the command would be:

  kermit -C "define \%%a foo, define phonenumber 7654321"

Here we need to double the percent sign rather than the backslash because
of DOS shell quoting rules.

Note that you can not set values for \%1..\%9 this way.  The -C command-line
option defines a macro called CL_COMMANDS whose definition is the material
between the quotes, and then executes it.  But \%1..\%9 are local to the macro
they are passed to or defined in, and cease to exist when the macro exits.

13.8. Per-Character Echo Check with the OUTPUT Command

Sometimes the OUTPUT command must be used to send commands or data to a device
in "echoplex" mode, meaning that characters must be sent one at a time, and
the next character can not be sent until the echo from the previous one has
been received.  For example, a certain PBX might have this characteristic.
Let's say a Kermit script is used to program the PBX.  If characters are sent
too fast, they can be lost.  It would seem that the command:

  SET OUTPUT PACING <milliseconds>

could be used to take care of this, but the pacing interval is constant and
must be set large enough to allow even the slowest echo to finish.  If the
script is large (an actual example is 14,000 lines long), this can cause it
to take hours longer than it needs to.

Here is a macro you can use to OUTPUT a string in an Echoplex environment:

  define XOUTPUT {
      local \%c
      set output pacing 0
      while defined \%1 {
	  asg \%c \fsubstr(\%1,1,1)
	  asg \%1 \fsubstr(\%1,2)
	  output \%c
	  input 2 \%c
      }
  }


Usage: xoutput string-with-no-spaces
   or: xoutput { string that contains spaces }
C-Kermit 6.0 or later is required.

It sends one character at a time and then waits up to 2 seconds for the
character to be echoed back, but continues to the next character as soon
as the echo appears, so no time is wasted.  You can add an IF FAIL clause
after the INPUT in case you want to do something special about failure
to detect an echo within the timeout period.  Obviously you can also change
the 2-second limit, and adjust the script in any other desired way.

(End of CKERMIT.BWR)