CKCKER.BWR          "Beware File" for C-Kermit Version 5A        -*- text -*-

Applies to 5A(184).
Last update: Mon Oct 12 15:17:17 1992

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

  Copyright (C) 1985, 1992, Trustees of Columbia University in the City of New
  York.  Permission is granted to any individual or institution to use this
  software as long as it is not sold for profit.  This copyright notice must be
  retained.  This software may not be included in commercial products without
  written permission of Columbia University.

Report problems, suggestions, fixes, etc, to Frank da Cruz:

  Internet: fdc@watsun.cc.columbia.edu  (or)  fdc@columbia.edu
  BITNET/EARN: FDCCU@CUVMA

Columbia University Center for Computing Activities
612 West 115th Street, New York, NY  10025  USA


FILES

C-Kermit files all begin with the letters CK.  The third character tells
which C-Kermit implementation it belongs to: U for UNIX, V for VMS, D for
Data General AOS/VS, O for OS/2, S for Atari ST, 9 for OS-9, M for Macintosh,
etc.  The file naming conventions are given in detail in the file CKAAAA.HLP.

File naming conventions are listed in CKAAAA.HLP.  Installation instructions
are in the files CK?INS.DOC (? = U for UNIX, V for VMS, etc).

Program function and variable definitions are in CKAPLM.DOC (for programmers
only).

If you have trouble building or installing the program, or if the program you
have built behaves in a bizarre fashion, BE SURE TO READ CK?INS.DOC as well as
the rest of this file, and the system specific CK?KER.BWR file.


DOCUMENTATION

C-Kermit 5A is documented in the book "Using C-Kermit" by Frank da Cruz
and Christine M. Gianone, Digital Press, Burlington, MA, USA.  Publication
date: Fall 1992.


THE C-KERMIT COMMAND PARSER

 . There is no command recall or retry.
 . VAX/VMS-style command parsing (arrow keys, etc) is not supported.
 . EMACS- or VI-style command line editing is not supported.
 . Typeahead is presently not allowed.
 . Editing keys are hardwired (Ctrl-U, Ctrl-W, etc).

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

If you quote special characters in a filename (e.g. in the SEND command),
filename completion may appear 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.


DIALING

    IMPORTANT: In edit 184, the meaning of SET DIAL SPEED-MATCHING was
    reversed from its previous (less intuitive meaning).  Now, ON means
    that C-Kermit changes its speed according to the modem's CONNECT
    report, OFF means that C-Kermit does NOT change its speed.

C-Kermit knows about a large number of modems, depending on how it was
built (type "set modem ?" to see the supported modem types; type "show
features" to see any specific modem-related configuration options).
This knowledge is imbedded in the SET MODEM and DIAL commands.  If you are
having trouble dialing your modem:

 a. SET DIAL DISPLAY ON to watch the dialing interactions between C-Kermit
    and your modem.

 b. Make sure you have given the SET MODEM <name> command BEFORE you
    issued the SET LINE and DIAL commands, and make sure that the modem
    name that you specified corresponds to the actual modem that you are
    trying to use.

 c. Make sure you have given a SET SPEED command to connect to the modem
    at a speed it supports (like 2400), AFTER you gave the SET LINE command.

 d. If that doesn't work, give the command SET DIAL MODEM-HANGUP OFF and
    try again.

 e. If that doesn't help, Give the command SET DIAL HANGUP OFF and try again.

 f. If that doesn't work, give the command SET CARRIER OFF and try again.

 g. If that doesn't work, maybe your modem is configured incorrectly.  Use
    SET DIAL INIT-STRING <text> to have C-Kermit send the proper
    configuration commands to the modem at the commencement of dialing.

 h. Check the hardware configuration of your modem, and check the cable that
    connects your modem to your computer.

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".

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

 1. (only if neccessary) 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.

The SET DIAL KERMIT-SPOOF command works only for Telebit and US Robotics
modem types.  See Telebit section for further information.

The SET DIAL MNP-ENABLE command only works for Telebit modems.  It is OFF
by default, to prevent (a) loss of incoming data after successful connection
to a non-MNP modem, and (b) transmission of garbage characters to the remote
host when the answering modem is not MNP capable (which can ruin automatic
speed detection, login processes, script program execution, etc).  See Telebit
section for details.

If C-Kermit's dialing methods are insufficient for your purposes, you can
write a C-Kermit script program to do the dialing.  Or you can use (or write)
another program to accomplish the dialing, and then run C-Kermit "underneath"
your dialing program by giving it the open file descriptor:

  kermit -l <n> -m unknown

where <n> is the numeric file desciptor.  (This feature is available in the
UNIX and OS/2 versions of C-Kermit.)  Or you can modify the ckudia.c module.


HAYES AND COMPATIBLE MODEMS

C-Kermit should work correctly with Hayes and other modems that use the AT
command set.  These include Hayes 1200, Hayes 2400, and Hayes 9600 bps modems,
compatibles, as well as Telebit and HST modems.  See the next section for
Telebit information.  C-Kermit sends AT commands to the modem and then reads
the modem's response.  The code is designed to work whether the modem is
configured to echo its commands (E1) or not (E0), and whether it replies with
numeric (V0) or word (V1) result codes.  C-Kermit does not change the echoing
state or result code mode of the modem.  However, C-Kermit issues the Q0
command to the modem to ensure that it *does* produce result codes.

C-Kermit assumes that the modem's Command Line Terminator (S3) is set to 13
(carriage return).  If it is not, C-Kermit's dialog with the modem might not
work correctly.


TELEBIT MODEM DIALING SUPPORT

There are numerous Telebit modem models, with differing capabilities and
features.  C-Kermit tries to support them all in a model-independent way.  
To use a Telebit modem, any model, SET MODEM as follows:

TELEBIT
  Dial and attempt to connect using the highest protocol appropriate to
  the interface speed between the computer and the modem, and fall back
  automatically to the highest protocol and speed supported by the answering
  modem.  For example, if your interface speed is 19200 bps and you have a
  PEP-capable Telebit, it will start in PEP mode, fall back to one of the
  2400-bps standards, then one of the 1200 bps standards, etc, depending on
  its configuration (see your Telebit manual).

PEP-TELEBIT
  Dial in PEP mode, and connect only if the remote modem answers in PEP mode.
  Does not work with Telebit models that do not support PEP.  See Table III.

V32-TELEBIT
  Dial in V.32 mode (9600 bps), fall back from there.  Works only with Telebit
  models that support V.32; see Table III.  NOTE: V.32 calls are supposed to
  work no matter what your interface speed is, but it has been observed that
  when calling certain non-Telebit V.32 modems, the connection is not made
  successfully unless C-Kermit's interface speed to the Telebit is 9600.

V42-TELEBIT
  Enable V.42 error correction, allowing fallback to MNP, and from there to
  direct (no error correction).  NOTE: Fallback to MNP from V.42 is allowed
  even if DIAL MNP-ENABLE is OFF.  Works only with Telebit models supporting
  V.42 error control.  See Table III.

SLOW-TELEBIT
  Dial at 2400 bps (V.22bis), fall back from there.

Telebit modems come in many models that are incompatible with each other, not
only as to features, but also which commands control which features.  The
features, commands, and acceptable S-register values (and their meanings) can
vary not only among models, but even among different ROM versions on the same
model.  Rather than have dozens of separate SET MODEM TELEBIT-xxx commands,
C-Kermit queries the modem for its model number with an ATI command, and then
adjusts its modem commands accordingly.  Responses to the ATI command are
shown in Table I.


---------------------------------------------------------------------------
Table I: Telebit Modem ATI Command Responses
---------------------------------------------------------------------------
  ATI  Model Numbers           Examples
  ---  -------------           --------
  123                          Telebit in "total Hayes-1200" emulation mode
  960                          Telebit in Conventional Command (Hayes) mode
  961  RA12C                   IBM PC internal original Trailblazer
  962  RA12E                   External original Trailblazer, DCA Fastlink,
                                 or Racal-Milgo RM1822
  963  RM12C                   Rackmount original Trailblazer
  964  T18PC                   IBM PC internal Trailblazer-Plus (TB+)
  965  T18SA, T2SAA, T2SAS     External TB+, T1600, T2000, T3000, WB, and later
                                 or Ven-Tel Pathfinder EC18K (see below)
  966  T18RMM                  Rackmount TB+
  967  T2MC                    IBM PS/2 internal TB+
  968  T1000                   External T1000
  969  ?                       QBlazer
  971  T25SA                   External T2500 or T1500 (see below)
  972  T25RM                   Rackmount T2500
---------------------------------------------------------------------------


Certain incompatible models show the same the response to ATI.  The ATI3
command is used to differentiate among them, as shown in Table II.


---------------------------------------------------------------------------
Table II: Telebit Modem ATI3 Command Responses
---------------------------------------------------------------------------
ATI        If ATI3 Response 
Response   Contains            Telebit Model Is
--------   -----------------   ----------------
 965       "T1600"             T1600
 965       "T3000"             T3000
 965       "World"             WorldBlazer
 965       "Version B"         TrailBlazer-Plus or T2000 external version 1
 965       "TBSA"              TrailBlazer-Plus or T2000 external version 2
 965       "TBRM"              TrailBlazer-Plus or T2000 rackmount version 2
 965       "DC"                Ven-Tel Pathfinder EC18K (= TB+ version 1)
 971       "T1500"             T1500
 971       (anything else)     T2500
----------------------------------------------------------------------------


The features of the various models and the commands used by Kermit to control
them are shown in Table III.  The commands in the PEP column are used to force
PEP and allow compression (SET MODEM PEP-TELEBIT).  The commands in the V.32
column are used with SET MODEM V32-TELEBIT.  The commands in the V.42 column
are used with SET MODEM V42-TELEBIT.  The commands in the MNP column are used
if SET DIAL MNP-ENABLE is ON and the modem type is TELEBIT, PEP-TELEBIT, or
V32-TELEBIT, SLOW-TELEBIT, but not V42-TELEBIT; if SET MNP-ENABLE is OFF, the
S-registers in the MNP column are set to 0.  The Pass BREAK column shows the
commands used to ensure that the modem passes the BREAK signal through (rather
than treating it as an "escape-to-command-mode" signal).


-------------------------------------------------------------------------------
Table III.  Telebit Modem Features and Commands
------+---------------------+-------+--------+--------+-------------+----------
      |                     |       |        |        |             | Kermit
Model |      PEP            | V.32  |  V.42  | MNP    | Pass BREAK  | Spoof
------+---------------------+-------+--------+--------+-------------+----------
TB    | S50=255 S110=1      |  No   |  No    | S95=2  |    S54=3    | PEP only
TB+   | S50=255 S110=1      |  No   |  **    | S95=2  |    S54=3    | PEP only
T2000 | S50=255 S110=1      |  No   |  **    | S95=2  |    S54=3    | PEP only
T1000 | S50=255 S110=1      |  No   |  No    | S95=2  |    S54=3    | PEP only
T2500 | S50=255 S110=1      | S50=6 |  **    | S95=2  |    S54=3    | PEP only
T1500 |      No             | S50=6 |  **    | S95=2  |    S54=3    | PEP,V.32
------+---------------------+-------+--------+--------+-------------+----------
T1600 |      No             | S50=6 | S180=2 | S180=3 | S61=0 S63=0 | PEP,V.32
T3000 |      No             | S50=6 | S180=2 | S180=3 | S61=0 S63=0 | PEP,V.32
QB    |      No             | S50=6 | S180=2 | S180=3 | S61=0 S63=0 | No
WB    | S50=255S190=1S191=7 | S50=6 | S180=2 | S180=3 | S61=0 S63=0 | PEP,V.32
------+---------------------+-------+--------+--------+-------------+----------
**  For V.42 error control: "S50=0 S95=2 S97=1 S98=3 S106=1".

All models but the QBlazer support Kermit spoof (but see below).

Group I (old command set):

          TB = Original TrailBlazer (PEP, MNP, V.22bis, V.22, Bell 212A & 103)
         TB+ = TrailBlazer-Plus = TrailBlazer + V.42 (but only in new ROMs)
       T1000 = TrailBlazer-Plus, speed <= 9600, no PEP compression
       T2000 = TrailBlazer-Plus + SDLC (not used by Kermit, so same as TB+)
       T2500 = TrailBlazer-Plus + V.32 (9600 bps)
       T1500 = T2500 minus PEP

Group II (new command set):

       T1600 = V.32, MNP, V.22bis, V.22, V.23, Bell 212A & 103
QB = QBlazer = T1600 without Kermit spoof and minus some other options
       T3000 = T1600 + V.32bis (14400 bps)
 WorldBlazer = T3000 + PEP + LZ and V.42bis compression + 76800 & 115200 bps.

C-Kermit does not attempt to control whether the modem changes its interface
speed to match the connection speed -- that is up to you; you can configure
the modem any way you prefer (using S51), but make sure that the modem's
configuration agrees with C-Kermit's DIAL SPEED-MATCHING setting.  When DIAL
SPEED-MATCHING is OFF (which is the default), C-Kermit will change its
interface speed automatically according to the speed reported in the modem's
CONNECT message; when it is ON, C-Kermit does not change the speed.

The DIAL KERMIT-SPOOF command is only effective for the Telebit models that
supply a Kermit spoof, that is, all but the QBlazer.  If the Telebit model is
TrailBlazer, TrailBlazer-Plus, T1000, T2000, or T2500, PEP mode is forced even
if your SET MODEM command specified a Telebit modem type other than
PEP-TELEBIT, because the Kermit spoof only works in PEP mode on those models.
On the other models supporting the Kermit spoof, it works on both PEP
connections and V.32 MNP (but not V.42) connections.  Thus, you might also
have to SET MODEM MNP-ENABLE ON in order to get the Kermit Spoof to work on
these newer models when making a V.32 connection.

SHOW DIAL does not show the complete initialization string for Telebit modems.
Telebit modems are initialized in several steps, and the initialization
command depend upon your current communication parameters, which model of
Telebit modem you have (which C-Kermit learns during the modem initialization
process), and other factors.  If you use the SET DIAL INIT-STRING command to
change the initialization string, this disables the multistep process and uses
only the string that you have specified.

If you want to use the built-in multi-step process, but you also want to
override one or more of the settings that are done in this process, or add
additional settings, you can use SET DIAL DIAL-COMMAND to add commands to the
dial string (which is normally ATD%s\13), for example "SET DIAL DIAL-COMMAND
AT&C1&D2S181=1DT%s\13".

FLOW-CONTROL versus dialing: If you have SET FLOW to any of the hardware
options supported by your version of C-Kermit, such as RTS/CTS, and if
C-Kermit knows how to set the flow control on your modem, it will do this as
part of the DIAL command.  Several cautions are needed here:

 . If C-Kermit's FLOW-CONTROL setting is Xon/Xoff or other type of software
   flow control, C-Kermit will not attempt to change your modem's flow control
   setting, since software flow control is most commonly used end-to-end.  One
   way to engage Xon/Xoff flow control directly between C-Kermit and the
   local modem is to change your modem's DIAL INIT-STRING to do it.

 . If your version of C-Kermit does not support SET FLOW RTS/CTS (or other
   hardware options), then C-Kermit will not attempt to change your modem's
   flow control setting.  Change your modem's DIAL INIT-STRING to do it.

Hardware flow control options are presently handled only for Telebit modems.
On other modem types, you can set the flow control outside of Kermit, or
change Kermit's DIAL INIT-STRING.

Most 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; if not, you can put the appropriate command in the
DIAL INIT-STRING or DIAL-COMMAND.

C-Kermit has no special support for "TIES" (Time Independent Escape Sequence)
modems, and no mechanism for preventing accidental escape to command mode when
such modems are used.  A TIES 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 transmitting 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.  If you are using
a Telebit TIES modem, you can turn off the modem's escape sequence recognition
with:

  AT S48=0 S2=255

This is recommended especially during file transfer, in case the file happens
to contain three plus signs in a row.  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.


TERMINAL EMULATION

Except for the 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.

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

 - If you SET your TERMINAL CHARACTER-SET to anything besides TRANSPARENT,
   C-Kermit translates your keystrokes (after applying any SET KEY
   definitions) before sending them to the remote host, and translates the
   characters received from the remote host before sending them to 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.

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


FILE TRANSFER

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 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.

Some communication software, notably a certain popular commercial package,
claim to implement sliding windows, but do not do so correctly.  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.

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
and OS/2 record the file date only to the nearest minute.  This can cause
update operations to send more files than necessary.

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.  (NOTE: a fix is in the works, at least for UNIX, which pipes the
incoming file to the mail or print program.)

The STATISTICS command will produce an incorrect 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
will 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.

When transferring extremely large files (e.g. many megabytes) in local mode,
the Time Remaining and Percent Done values reported by the file transfer
display might be incorrect, due to arithmetic overflow.


SCRIPT PROGRAMMING

You can't use END or RETURN statements in FOR, WHILE, and XIF commands (you
can use them, but they won't do what you expect).

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.  C-Kermit does not know the collating
sequence for different character sets and languages.

The INPUT command does not accept NUL (\0) characters in its search string
(well, it does, but the NUL terminates the search string rather than being
included as part of it).  This is because C-Kermit's character strings are
terminated internally by NUL, to allow all of C-Kermit's string comparison
and manipulation functions to work with the \v(input) variable (i.e. the
contents of the INPUT buffer).

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.

GOTO can be used sort of like switch/case.  For example, if you know that
the value of \%a is 1, 2, or 3, you can "goto \%a" provided you have labels
:1, :2, and :3.  What it missing, however, is a way to trap failing GOTOs,
similar to the "default:" clause of a C switch() statement.


(End of CKCKER.BWR)