Columbia Kermit/kermit.zip/c-kermit/ckiker.txt

Text File | 2020-01-01 | 16KB | 331 lines

PREFACE

Most of this short introduction to C-Kermit is by Jack Rouse of the
Software Distillery and SAS Institute.  The current supporter of Amiga
Kermit is Stephen Walton, reachable via email as
"[e-mail]" on the Internet.

INTRODUCTION

This version of Amiga Kermit is a port of the Unix C-Kermit which attempts
to reproduce as much of the functionality of Unix version as possible.  I
had two main goals in porting C-Kermit:  I wanted a reliable remote file
transfer utility, and I wanted to investigate the use of the AmigaDOS
and Exec environments.

Amiga Kermit currently provides a line oriented user interface.  I currently
have no specific plans to implement menuing, but there are several places in
Kermit where a menu interface would be an asset.  In this version of Kermit,
I have concentrated on the functional aspects.

As I have stated before, this is a port of the Unix C-Kermit.  The
definitive documentation is the book, "Using C Kermit," by Frank da
Cruz and Christine Gianone.  Therefore, only Amiga specific features
are noted below.

INVOKING C-KERMIT

Amiga Kermit is usually invoked from a CLI process.  However, you can
also start it from a Tool type icon.  Create a Tool icon, called
Kermit.info, and make sure that it contains a ToolType entry for
WINDOW= followed by some window specification.  This is actually a
small dummy window, as C Kermit will open and use its own window.

From a CLI window, you generally enter:
   KERMIT
or
   RUN KERMIT
to execute Kermit and start up the Kermit command interpreter.  Make sure
you set your stack to at least 10000 with the AmigaDOS Stack command first.
Kermit will create its own window and greet you with:

   Executing s:CKERMIT.INI for Amiga...
    Services directory is s:CKERMIT.KSD
   Executing s:CKERMOD.INI...
   Good Evening.
   C-Kermit 6.0.192, 6 Sep 96, for Commodore Amiga (SAS/C)
    Copyright (C) 1985, 1996,
     Trustees of Columbia University in the City of New York.
   Default file-transfer mode is TEXT
   Type ? or HELP for help.
   [Work:src/kermit/ck/192] C-Kermit>

   assuming that you are using the default distributed S:CKERMIT.INI file.
The cursor will appear following the C-Kermit> prompt.  Typing ? will
produce a list of the items that can be entered at any point.  Typing ?
here will produce a list of commands:

 add           directory     introduction  quit          stop
 answer        disable       kermit        read          suspend
 apc           do            local         receive       switch
 ask           echo          log           redial        take
 askq          eightbit      lookup        reget         translate
 assign        enable        mail          reinput       transmit
 bug           end           minput        remote        type
 bye           evaluate      mmove         rename        undefine
 cd            exit          move          resend        version
 check         finish        msend         retrieve      wait
 clear         for           msleep        return        while
 close         get           news          run           who
 comment       getc          open          save          write
 connect       getok         output        script        write-line
 date          goto          pause         send          xecho
 declare       hangup        pdial         server        xif
 decrement     help          print         set
 define        if            psend         show
 delete        increment     push          space
 dial          input         pwd           statistics
or one of the tokens: !#;:@

Typing ? at various points during command entry will help you navigate
through the command processor.  The 'help' command is also quite useful.
Typing 'help' alone gets information about command entry:

  C-Kermit 6.0.192, 6 Sep 96, Copyright (C) 1985, 1996,
  Trustees of Columbia University in the City of New York.

    Type INTRO   for a brief introduction to C-Kermit.
    Type VERSION for version and copyright information.
    Type HELP    followed by a command name for help about a specific command.
    Type NEWS    for news about new features.
    Type BUG     to learn how to get technical support.
    Press ?      (question mark) at the prompt, or anywhere within a command,
                 for a menu (context-sensitive help, menu on demand).

    From system level, type "kermit -h" for help about command-line options.

  DOCUMENTATION: "Using C-Kermit" by Frank da Cruz and Christine M. Gianone,
  2nd Edition, Digital Press / Butterworth-Heinemann 1997, ISBN 1-55558-164-1.
  To order: [phone] or [phone].  PLEASE PURCHASE THE MANUAL.
  It shows you how to use C-Kermit and answers your questions; sales of this
  book are the primary source of funding for C-Kermit development and support.

but 'help' can be used with command lines to get command descriptions.  For
example:

   C-Kermit>help bye
   Shut down and log out a remote Kermit server

The Kermit command processor is normally exited with the 'EXIT' command.
During Kermit protocol, you can type CTRL-C or CTRL-D to interrupt and
exit Kermit.  Depending on the version of the C runtime libraries used
to link Kermit, the interrupt may also be active during command input, but
it is disabled during connect mode.  You will get a requestor when the
interrupt is activated to allow you to choose to continue Kermit.  However,
any serial read or write that was interrupted will still be aborted.

Kermit can also be used without the command processor by specifying an
action on the command line.  You can enter 'kermit -h' at the CLI prompt
to get a list of command line options.  However, unless input is redirected,
or the -q (quiet) option is specified, Kermit will still create a window
for protocol monitoring and interruption.  'KERMIT <*' can be used to
run Kermit completely within the CLI window; however, this does not allow
you to enter control characters, and no console input is seen until you
enter return.  Input and output can be redirected to files to take advantage
of C-Kermit command line file transfer options.  Unfortunately, AmigaDOS
does not implement pipes (yet).

KERMIT INITIALIZATION AND SERIAL SETTINGS

Amiga Kermit uses the serial device or a reasonable emulation thereof.
Three sources are used to initialize the serial parameters.  First, the
default serial configuration, as set by Preferences, is copied.  This
includes baud rate, and under version 1.2 of the Workbench, parity, modem
control (7-wire vs. 3-wire), and flow control. Second, command line
parameters can be used to override these settings. For example:
   kermit -b 1200 -p e
can be used to select 1200 baud and even parity independently of the
Preferences settings.  Finally, if the command processor is used,
Kermit looks for a "CKERMIT.INI" initialization file, first in the "s:"
directory, then in the current directory, providing that the disk
containing each directory is present in the Amiga.  The "CKERMIT.INI"
file contains C-Kermit commands which can be used to initialize the
C-Kermit environment as desired.

C Kermit is distributed with a default CKERMIT.INI file which you
should always use.  It includes some Amiga-specific initialization;
sugggestions for more are welcome.  CKERMIT.INI also executes the
commands contained in the file CKERMOD.INI, which is searched for along
the same path as CKERMIT.INI itself.  Your personal customization
commands should be done here.

The Kermit SET LINE command has a special form in Amiga Kermit, namely:

SET LINE device/unit

where "device" is the name of a device (including the .device extension)
and "unit" is the unit number.  The default setting is equivalent to

   C-Kermit>SET LINE serial.device/0

to give a simple example.

Kermit allows you to set any baud rate between 110 and 292000 baud;
however, it will complain if the baud rate is nonstandard (I added this
feature after several attempts to use my modem at 12000 baud).  Rates of
110 and 111 baud are implemented as 112 baud.  Rates above 38400 baud can
be used for connect mode, but they are not very useful for file transfer.
The file transfer rate is limited by packet retries due to transfer
errors, and the overhead time spent constructing packets.

Amiga Kermit opens the serial device in exclusive mode by default.
However, an open in shared mode can be forceed by following the name
and unit number on the SET LINE command with "/S";  for example:

   C-Kermit>SET LINE SERIAL.DEVICE/0/S

This allows other programs, like dialers, to use the serial line at the
same time, without exiting Kermit.  This could also allow in theory a
terminal emulator to be used simultaneously with Kermit.  However, if
two programs are reading from the serial line at the same time, the
results are unpredictable.  Any such program, therefore, would have to
be disabled from reading while Kermit is performing file transfer or is
in connect mode.  For these reasons, Commodore-Amiga strongly
recommends against sharing the serial port, but Amiga Kermit includes
the capability should you need it.

Note that Kermit since does its own parity generation and stripping, so
it always sets the serial device to use eight bit characters with no
parity.

WILDCARDING

Both the SEND command invoked from the Amiga and a GET sent to an Amiga
in server mode use allow wildcarding, in the Unix style.  Thus, '*'
wildcard matches an arbitrary string while '?' matches an arbitrary
character.  Therefore, to get all the C source files which begin with 'cki'
from the Amiga server, you could use the command:

   C-Kermit>GET cki*.c

Multiple '*' wildcards can be used in a pattern; however, beware that
most Unix C-Kermit's may not completely support this form.  Also, the
wildcarding that is used in local and remote server commands that invoke
AmigaDOS commands is the AmigaDOS form.

LOCAL AND REMOTE COMMANDS

Amiga Kermit provides several ways to invoke AmigaDOS commands from within
Kermit.  Entering '!' at the Kermit prompt will create a CLI process running
in its own window, and wait for it to terminate.  The form '! command' will
invoke the given command command with its output going to Kermit's window.
There is currently no way to pause the output of commands invoked his way,
other than the stopgap use of the right mouse button.  The form 'REMOTE
HOST command' can be sent to the Amiga server to execute the given command
remotely on the Amiga.  Because of the way AmigaDOS Execute() function
works, commands invoked in either the '! command' or 'REMOTE HOST command'
forms have NIL: as their standard input.  Some AmigaDOS commands that
require input, such as DiskCopy and Format, do not recognize the immediate
end of file that they receive under this condition, causing them to hang.

In addition to the methods given above, various AmigaDOS commands are
invoked by local Kermit commands, and generic remote commands.  These
are listed below:

   AmigaDOS command    Local command      Remote generic command
   DELETE files        --none--           REMOTE DELETE files
   TYPE files          --none--           REMOTE TYPE files
   INFO                SPACE              REMOTE SPACE
   LIST obj            DIRECTORY obj      REMOTE DIRECTORY
   STATUS              --none--           REMOTE WHO

Any parameters to these commands are expected to use AmigaDOS conventions,
including AmigaDOS wildcarding.  Note that in order to pass a '?' through
the C-Kermit command processor, it must be prefixed with a '\'.

You can change the current directory of the Kermit process locally with the
CWD command and remotely with REMOTE CWD.  The local CWD command prints
out the name of the current directory afterwards.  If no new directory
is given, the current directory is not changed, so CWD alone can be used
to determine where the current directory is.  (The default CKERMIT.INI
supplied with Kermit creates a prompt with the current dirrectory in
it.)

SERVER MODE

Amiga Kermit completely implements server mode, including the ability
to execute CLI commands remotely.  Currently CLI commands are executed
with their standard output directed to RAM:PIPE-HOLDER, which is then
written back to the commanding Kermit after the command completes.

There are a few limitations on the commands that can be executed remotely.
First of all, if they produce voluminous output, the output should be
redirected (redirection is supported on the REMOTE HOST command line)
to avoid using all free memory for the output file.  However, the
commanding Kermit will probably timeout in the middle of the execution
of any such command.  The best way to use these commands is to
   REMOTE HOST RUN command >outfile parameters
then use REMOTE WHO (which invokes STATUS) to monitor the command for
completion.

The input stream for remote commands is NIL:, which is not handled
intelligently by all Amiga commands.  For example, 'REMOTE HOST diskcopy
df0: to df1:' hangs indefinitely while waiting for NIL: to press return.
Finally, since each command is executed in a separate CLI, commands that
set unshared process parameters, like 'cd',  will have null effect (but
'REMOTE CWD dir' can be used instead).

While server mode is active, AmigaDOS requestors are disabled.  This
avoids requiring operator intervention to reset a requestore when the Amiga
server is told to use a file on a disk that does not exist or is write
protected.  However, disabled requestors are currently not inherited by the
CLI processes that the server creates to execute remote commands.
Therefore, a remote AmigaDOS command can still cause the server to become
hung.

To shut down the Amiga server, enter BYE or FINISH at the commanding
Kermit.  FINISH exits to whatever level the server was invoked from,
while BYE exits Amiga Kermit altogether.

CONNECT MODE

Connect mode on Amiga Kermit currently provides you with a standard
AmigaDOS console device window.  Using the default Preferences
setting, this gives a 23 row by 77 column screen.  However, the
MoreRows program allows you to increase the size of the Workbench
window beyond the 640 by 200 default size; increasing the number of
rows by 8 and the number of columns by 16 will allow a 24 row by 80
column Kermit window.  The Amiga console device is used to provide
ANSI terminal emulation.  While you are in connect mode, you can give
single character commands which are prefixed by an escape character
which can be set from within C-Kermit.  By default, the escape
character is CTRL-\.  You can use '<escape>H' to close the serial
device and exit connect mode, which makes the DTR line drop causing
most modems to hang up the phone line.

You can currently get a 25 by 80 screen in Kermit by means of a kludge.
Entering the Kermit command line

     echo \27[25t\27[80u\27[3x\27[10y\12

activates console device private escape sequences that cause the console
to use a 25 by 80 region, overwriting the borders of the Kermit window.
Using window gadgets will cause the borders to be redisplayed, but the
display can be cleaned up by typing ctrl-L in command mode.  To reset
the window to its normal condition, allowing resizing, use:


    ECHO \\033[t\\033[u\\033[x\\033[y\\014

and then activate a window gadget to refresh the borders.  These commands
can be placed into Kermit TAKE files.

In addition to the standard connect mode commands, extra logging control
has been added.  If a session log file is open, the '<escape>Q' sequence
allows you to temporarily suspend logging.  The '<escape>R' sequence
resumes logging if it has been suspended.

Features have also been added to prevent deadlocks while in connect mode
due to spurious XOFF's or bad modem control line states.  When connect
mode is unable to send serial output, keyboard characters are queued until
they can be transmitted.  Queuing continues as long as space is available
in the output buffer.  If the buffer, which is 64 characters long, fills up,
the next keyboard input is discarded and the display 'beeps'.  To get out
of a deadlock situation, you can either exit connect mode, or send a break.
In either case, the output queue is flushed, and current serial output
character is given one second to finish transmitting.  If it does not
complete, the output is aborted, and XOFF mode reset as appropriate.  Then
connect mode is exited or a break is sent, as specified.  When output
characters are queued, connect status (accessed by '<escape>S') will
indicate the number of queued output characters.