CD Actual 15/CDACTUAL15.iso/cdactual/program/asm/MSKERMIT.ZIP/MSKERMIT.DOC

Text File | 1986-05-17 | 92.2 KB | 2,531 lines

                                      79


9. MS-DOS KERMIT

Program:    Daphne Tzoar and Jeff Damens, Columbia University; contribu-
        tions by many others.
Language:   Microsoft Macro Assembler (MASM)
Documentation:
        Frank  da  Cruz,  Columbia    University; Herm Fischer, Litton
        Data Systems, Van Nuys CA.
Version:    2.26
Date:        July 1984


Kermit-MS Capabilities At A Glance:

  Local operation:             Yes
  Remote operation:             Yes
  Transfers text files:          Yes
  Transfers binary files:         Yes
  Wildcard send:             Yes
  ^X/^Y interruption:             Yes
  Filename collision avoidance:      Yes
  Can time out:              Yes
  8th-bit prefixing:             Yes
  Repeat count prefixing:         Yes
  Alternate block checks:         Yes
  Terminal emulation:             Yes
  Communication settings:         Yes
  Transmit BREAK:             Yes
  IBM mainframe communication:         Yes
  Transaction logging:             No
  Session logging:             Yes
  Raw transmit:              No
  Act as server:             Yes
  Talk to server:             Yes
  Advanced server functions:         No
  Advanced commands for servers:     Yes
  Local file management:         Yes
  Handle file attributes:         No
  Command/init files:             Yes
  Command macros:             Yes

Kermit-MS is a program that implements the KERMIT file transfer protocol
for the IBM PC and several  other  machines  using  the  same  processor
family    (Intel    8088  or  8086)  and  operating system family (PC-DOS or
MS-DOS, henceforth referred to collectively  as  MS-DOS,  versions  1.1,
2.0,  and  2.1,  and thereafter).  This section will describe the things
you should know about the MS-DOS file system in order to make  effective
use of Kermit, and then it will describe the Kermit-MS program.

Version  2  of MS-DOS Kermit runs on a variety of systems, including the
IBM PC and XT, the HP-150, the DEC Rainbow 100 and 100+ (MS-DOS 2.05 and
above), the Wang PC, and there is a "generic" MS-DOS version.  Version 1
was adapted at various stages of development to run on other systems  as
well,    including   the   Heath/Zenith    100,  Tandy  2000,  Victor  9000
(Sirius-1), and Seequa Chameleon, and is still available for those  sys-
tems until support for them and others is added to version 2.
                                       80


The program operates under version 1.1 or 2.0 and above of DOS, although
some  features    require  the  functionality  of  2.0.     It  runs in ap-
proximately 80K of memory -- over and  above  the  memory  used  by  DOS
--  which means that your system should have at least 128K of RAM to use
version 2 of MS-DOS Kermit; smaller systems may still use Version 1.


9.1. The MS-DOS File System

The features of the MS-DOS file system of greatest  interest  to  KERMIT
users  are  the form of the file specifications, and the distinction be-
tween pre-MS-DOS 2.0 file names and newer file names which allow  direc-
tory paths.


9.1.1. File Specifications

MS-DOS 2.x file specifications are of the form

  DEVICE:\PATHNAME\NAME.TYPE

where  the  DEVICE is a single character identifier (for instance, A for
the first floppy disk, C for the first fixed disk,  D  for  a  RAM  disk
emulator),  PATHNAME  is  up  to 63 characters of identifier(s) (up to 8
characters each) surrounded by reverse slashes, NAME is an identifier of
up to 8 characters, and TYPE is an identifier of up to 3  characters  in
length.  Device and pathname may be omitted.  The first backslash in the
pathname may be omitted if the specified path is relative to the current
directory.    In the path field, "." means current directory, ".." means
parent directory.  Some DOS implementations (like Wang)  may  use  slash
"/" rather than backslash in the path field.

Pathname  is normally omitted, and cannot be specified for MS-DOS 1.x or
with those commands which allow MS-DOS 1.x use.   Device  and  directory
pathnames,  when  omitted, default to either the user's current disk and
directory, or to the current directory search path as specified  in  the
DOS  PATH  environment    variable,  depending on the context in which the
file name appears.

    When this manual says that a file is searched for "in  the  cur-
    rent path," it means that the PATH is searched first, and if the
    file  is not found, then Kermit-MS looks on the current disk and
    directory.    If the PATH environment variable  is  empty,  Kermit
    looks only at the current disk and directory.

NAME.TYPE is normally sufficient to specify a file, and only this infor-
mation is sent along by Kermit-MS with an outgoing file.

The  device,  path, name, and type fields may contain uppercase letters,
digits, and the special characters "-" (dash), "_" (underscore), and "$"
(dollar sign).     (For  use  only  among  MS-DOS  processors,  additional
filename  special  characters  allowed are "#&!%'`(){}".  DOS 1.x allows
others as well.).  There are no imbedded  or  trailing    spaces.    Other
characters  may  be not be included; there is no mechanism for "quoting"
otherwise illegal characters in filenames.    The  fields  of  the  file
specification  are set off from one another by the punctuation indicated
                                       81


above.

The  name  field is the primary identifier for the file.  The type, also
called the extension or suffix, is an indicator  which,  by  convention,
tells  what kind of file we have.  For instance FOO.BAS is the source of
a BASIC program named FOO;  FOO.OBJ  might  be    the  relocatable  object
module    produced  by  compiling  FOO.BAS; FOO.EXE could be an executable
program produced by linking FOO.OBJ, and so forth.  .EXE  and  .COM  are
the normal suffixes for executable programs.

The  MS-DOS  allows  a    group  of files to be specified in a single file
specification by including the special "wildcard" characters, "*" and "?
".  A "*" matches any string of characters from the current position  to
the  end of the field, including no characters at all; a "?" matches any
single character.  Here are some examples:

  *.BAS   All files of type BAS (all BASIC source files) in the  current
      directory.

  FOO.*   Files of all types with name FOO.

  F*.*      All files whose names start with F.

  F?X*.*  All  files whose names start with F and contain X in the third
      position, followed by zero or more characters.

  ?.*      All files whose names are exactly one character long.

Wildcard notation is used on many computer systems in similar ways,  and
it  is    the  mechanism    most  commonly used to instruct Kermit to send a
group of files.

    Note: Kermit-MS uses the "?" character for help  while  commands
    are  being    typed, so the single-character wildcard in Kermit-MS
    commands is "=" rather than "?".  For example

      Kermit-MS>send =.*

    would send files of all  types  whose  names  were    exactly  one
    character long.

Kermit-MS  users should bear in mind that other (non-MS-DOS) systems may
use different wildcard characters.  For instance the DEC-20 uses "%" in-
stead of "?" as the single character wildcard; when using  Kermit-MS  to
request a wildcard file group from a KERMIT-20 server, the Kermit-MS "="
must be replaced by the DEC-20 "%".


9.1.2. File Formats

MS-DOS    systems  store files as bulk collections of 8 bit bytes, with no
particular differences between text, program  code,  and  binary  files.
ASCII  text files consist of lines separated by carriage-return-linefeed
sequences (CRLFs), which conforms exactly to the way  Kermit  represents
text  files  during  transmission.   Since a non-MS-DOS receiving system
might need to make distinctions as to file type, you  may  need  to  use
                                       82


various  SET functions on the remote system to inform it that the incom-
ing file is of some particular (non-default) type, such as binary.    In
transmitting files between Kermit-MS's, regardless of file contents, the
receiving MS-DOS system is equally capable of processing text, code, and
data,  and  in    fact  has  no knowledge of how the bytes in the file are
used.

MS-DOS (unlike CP/M) is capable of pinpointing    the  end  of  file  with
precision  by keeping a byte count in the directory, so one would expect
no particular  confusion  in  this  regard.    However,  certain  MS-DOS
programs  continue to use the CP/M convention of terminating a text file
with a Control-Z character, and won't operate correctly unless this ter-
minating byte is present.  Therefore, Kermit-MS users should be aware of
a special SET EOF option for both incoming and outbound files, described
below.

Non-MS-DOS systems may well be confused by nonstandard ASCII files  from
Kermit-MS.   Files produced by Easywriter or Word Star, for example, may
need to be converted to conventional ASCII format prior to  transmission
by  commonly  available  "exporter"  programs.   Spreadsheet or database
files usually need special formatting to  be  meaningful  to  non-MS-DOS
recipients  (though  they can be transmitted between MS-DOS systems with
Kermit-MS).  Furthermore, files created by word processors (such as BLUE
or Easy Writer) that store formatting data at the end of the file, after
the control-Z and before physical end, will require  special  processing
via  SET  EOF to strip the formatting data, lest they confuse non-MS-DOS
recipients.


9.2. Program Operation

Kermit-MS can be  run  interactively,  from  a    batch  file,  or  as  an
"external"  DOS  command.    Commands  consist  of  one  or more fields,
separated by "whitespace" -- one or more spaces or tabs.

Upon initial startup, the program executes any    commands  found  in  the
file  MSKERMIT.INI  in    the  current path.  This initialization file may
contain command macro definitions, communications settings  for  one  or
more  ports,  or  any  other  Kermit-MS  commands.    Here  is    a sample
MSKERMIT.INI file:

  set warning on  ; Enable filename collision avoidance.
  ;
  ; Define some macros
  ;
  define unix set local-echo off, set flow xon, set timer off
  def ibm set parity odd, set local on, set handsh xon, set timer on
  def modem set port 2, set baud 1200
  def noisy set block-check 3, set send packet-length 40
  ;
  ; Select a port
  ;
  set port 1      ; Select COM1 for communications,
  set baud 4800   ; setting the speed to 4800 baud,
  connect      ; and make a terminal connection.
                                       83


Note  that  comments may be included by prefixing them with a semicolon.
The program can be run in several ways.


Interactive Operation:

To run Kermit-MS interactively, invoke    the  program  from  DOS  command
level by typing its name.  When you see the command's prompt,

  Kermit-MS>

you  may type Kermit commands repeatedly until you are ready to exit the
program, for example:

  A>
  A>kermit

  IBM PC Kermit-MS V2.26
  Type ? for help

  Kermit-MS>send foo.*

    informational messages about the files being sent

  Kermit-MS>get bar.*

    informational messages about the files being received

  Kermit-MS>exit
  A>

During interactive operation, you may edit the command you're  currently
typing    to  erase  the character most recently typed (BACKSPACE or DEL),
the most recent field (CTRL-W), or the entire command (CTRL-U).  In  ad-
dition, you may use the help ("?") and recognition (ESC) features freely
while  typing  Kermit-MS  commands.  A question mark typed at almost any
point in a command produces a brief description of what is  expected  or
possible  at  that  point;  for  this reason, Kermit-MS uses "=" for the
single-character match wildcard in local filenames.  ESC  typed  at  any
point,    even  in  a  local  filename, will cause the current field to be
filled out if what you have typed so far is sufficient to  identify  it,
and  will leave you in position to type the next field (or to type a "?"
to find out what the next field is); otherwise, the program will beep at
you and wait for you to type further characters.

Some Kermit-MS commands, like GET, SHOW KEY, SET KEY, may prompt for ad-
ditional information on subsequent lines.  If you have    reached  one  of
these  prompts    and  then  wish  to  cancel  the  command,  you may type
Control-C.

Summary of Kermit-MS Command Characters:

  BACKSPACE    Delete the character most recently typed.  May be  typed
        repeatedly  to    delete    backwards.    You  may    also use
        DELETE, RUBOUT, or equivalent keys.
                                       84


  CTRL-W    Delete    the most recent "word", or field, on the command
        line.  May be typed repeatedly.

  CTRL-U    Delete the entire command line.

  CTRL-C    Cancel    the  current   command     and   return    to   the
        "Kermit-MS>" prompt.

  ?        Type a brief message describing what you are expected to
        type in the current field.

  ESC        If  enough  characters have been supplied in the current
        field (keyword or file name) to  uniquely  identify  it,
        supply    the  remainder    of the field and position to the
        next field of the command.  Otherwise, sound a beep.

  =        Wildcard character for    matching  single  characters  in
        filenames, equivalent to MS-DOS "?".


Command Line Invocation:

Kermit-MS  may also be invoked with command line arguments from DOS com-
mand level, for instance:

  A>kermit send foo.bar

or

  A>kermit set port 1, set baud 9600, connect

In this case, help  and  recognition  are  not    available  (because  the
program  won't  start  running  until  after you type the entire command
line), and Kermit-MS will exit after completing the specified command or
commands.    Therefore,  when  invoked    with  command  line   arguments,
Kermit-MS  will behave as if it were an external DOS command, like MODE.
Note that several commands may be given on the command    line,  separated
by commas.


Batch Operation:

Like  other  MS-DOS programs, Kermit-MS may be operated under batch with
either command line arguments and/or TAKE files; Kermit  will  also  run
interactively  if invoked from batch, but it will read commands from the
keyboard and not the batch file.


9.3. Kermit-MS Commands

MS-DOS Kermit implements a large subset of the commands of "ideal"  Ker-
mit.  Here's a brief summary:

      BYE  to remote server.
    CLOSE  log file and stop logging remote session.
      CONNECT  as terminal to remote system.
                                       85


       DEFINE  macros of Kermit-MS commands.
       DELETE  local files.
    DIRECTORY  listing of local files.
       DO  a macro expansion.
     EXIT  from Kermit-MS.
       FINISH  Shut down remote server.
      GET  remote files from server.
     HELP  about Kermit-MS.
    LOCAL  prefix for local file management commands.
      LOG  remote terminal session.
       LOGOUT  remote server.
     PUSH  to MS-DOS command level.
     QUIT  from Kermit-MS
      RECEIVE  files from remote Kermit.
       REMOTE  prefix for remote file management commands.
      RUN  an MS-DOS program.
     SEND  files to remote Kermit.
       SERVER  mode of remote operation.
      SET  various parameters.
     SHOW  various parameters.
    SPACE  inquiry.
       STATUS  inquiry.
     TAKE  commands from file.

The  remainder    of  this  section concentrates on the commands that have
special form or meaning for MS-DOS Kermit.  Not  all  of  the  following
commands  are  necessarily  available on all MS-DOS systems, and some of
the commands may work somewhat differently between DOS versions.


9.3.1. Commands for File Transfer

The file transfer commands are SEND, GET, and RECEIVE.


                THE SEND COMMAND

Syntax:  SEND filespec1 [filespec2]

The SEND command causes a file or file group to be sent from  the  local
MS-DOS system to the Kermit on the remote system.  The remote Kermit may
be running in either server or interactive mode; in the latter case, you
should    already have given it a RECEIVE command and escaped back to your
PC.

filespec1 may contain a device designator, like "A:"  and  the  wildcard
characters  "*"  and/or "=".  The current release of Kermit-MS, however,
does not allow pathnames in the SEND command file specification.

If filespec1 contains wildcard characters then all matching  files  will
be  sent,  in  the same order that MS-DOS would show them in a directory
listing.  If filespec1 specifies a single file, you may direct Kermit-MS
to send that file with a different name, given in filespec2.    For  in-
stance, in the command

  Kermit-MS>send foo.bar framus.widget
                                       86


filespec2  begins  with the first nonblank character after filespec1 and
ends with the carriage return; thus it may contain blanks or  other  un-
usual  characters  that may be appropriate on the target machine.  Lower
case letters in filespec2 are raised to upper case for transmission.

If a file can't be opened for  read  access,  standard  MS-DOS  recovery
procedures will take place.  For example:

  Not ready error reading drive A
  Abort, Retry, Ignore?

If you select "Abort," you will be returned to DOS.

Files will be sent with their MS-DOS filename and filetype (for instance
FOO.TXT,  no device or pathname).  Each file is sent as is, with no con-
versions done on the data, except for possibly adding or deleting a ter-
minating Control-Z character (see the SET EOF command).

Once you give Kermit-MS the SEND command, the name of each file will  be
displayed  on  your  screen  as  the transfer begins; packet, retry, and
other counts will be displayed along with informational messages  during
the  transfer.      If  the file is successfully transferred, you will see
"Complete", otherwise  there  will  be  an  error  message.    When  the
specified operation is done, the program will sound a beep.

Several  single-character commands may be given while a file transfer is
in progress:

  ^X  (Control-X) Stop sending the current file and go on  to  the  next
      one, if any.

  ^Z  Stop sending this file, and don't send any further files.

  ^C  Return  to Kermit-MS command level immediately without sending any
      kind of notification to the remote system.

  ^E  Like ^C, but send an Error packet to the remote Kermit in  an  at-
      tempt to bring it back to server or interactive command level.

  CR  Simulate a timeout: resend the current packet, or NAK the expected
      one.

Control-X  and Control-Z send the proper protocol messages to the remote
Kermit to bring it gracefully to the desired state.    Control-C  leaves
the  remote  Kermit  in  whatever  state it happens to be in.  Control-E
"aborts" any protocol that is taking place.


              THE RECEIVE COMMAND

Syntax: RECEIVE [filespec]

The RECEIVE command tells Kermit-MS to receive a file or file group from
the other system.  Kermit-MS simply waits for the file to  arrive;  this
command  is  not to be used when talking to a Kermit server (use GET for
that).    You should already have issued a SEND command to the remote Ker-
                                       87


mit and escaped back to Kermit-MS before issuing the RECEIVE command.

If the optional filespec is provided, store the incoming file under that
name.     The filespec may include a device designator, or may consist of
only a device designator.  The incoming file is stored on the default or
specified device (current directory in DOS 2.0 and thereafter).   If  no
name  was  specified,  the  name from the incoming file header packet is
used; if that name is not a  legal  MS-DOS  file  name,  Kermit-MS  will
delete    excessive characters from it, and will change illegal characters
to the letter X.

If the optional filespec was provided, but more than one  file    arrives,
the  first  file  will    be  stored  under  the    given  filespec, and the
remainder will be stored under their own names,  but  on  the  specified
device.

If an incoming file does not arrive in its entirety, Kermit-MS will nor-
mally  discard it; it will not appear in your directory.  You may change
this behavior by using the command SET INCOMPLETE KEEP, which will cause
as much of the file as arrived to be saved in your directory.

The same single-character commands are available as during SEND:

  ^X  Request that the remote Kermit stop sending the current file,  and
      proceed  to  the    next one immediately.  Since this is an optional
      feature of the Kermit protocol, the remote Kermit might not  honor
      the request.

  ^Z  Request that the remote Kermit terminate the entire transfer; this
      is  also    an  optional feature that may or may not be supported by
      the remote Kermit.

  ^C, ^E, and CR operate in the same way as they do during SEND.

If the incoming file has the same name as a file  that    already  exists,
and  WARNING is set ON, Kermit-MS will change the incoming name (and in-
form you how it renamed it) so as not  to  obliterate  the  pre-existing
file.    If WARNING is OFF, the original file will be overwritten; if you
type ^X or ^Z to interrupt the transfer, you'll either get a partial new
file, or else both the old and the new file of that name will  be  lost,
depending  on  SET  INCOMPLETE.  In any case, when WARNING is off, files
with the same name as incoming files will not survive.

Caution: If an incoming file's name  (the  part  before  the  dot)  cor-
responds  to an MS-DOS device name, such as NUL, COM1, CON, AUX, or PRN,
output will go to that device, rather than to a  file  with  that  name.
This is a feature of MS-DOS.
                                       88


                THE GET COMMAND

Syntax: GET remote-filespec

The GET command requests a remote KERMIT server to send the file or file
group  specified by remote-filespec.  This command can be used only when
Kermit-MS has a KERMIT server on the other end of the connection.   This
means  that  you must have CONNECTed to the other system, logged in, run
KERMIT there, issued the SERVER command, and escaped back (e.g. ^]C)  to
the  local  Kermit-MS.    If the remote Kermit does not have a SERVER com-
mand, then you should use SEND and RECEIVE as described above.

You may use the GET command to specify a different name for storing  the
incoming.    Just  type  GET  alone  on a line, and you will be prompted
separately for the remote filespec and the local filespec:

  Kermit-MS>get
   Remote Source File: com1.txt
   Local Destination File: xcom1.txt

If more than one file arrives, only the first will be renamed.

The remote filespec is any string that can be a legal file specification
for the remote system; it is not parsed or validated locally.     It  can
contain  whatever wildcard or file-group notation is valid on the remote
system.  As files arrive, their names will be displayed on your  screen,
along  with packet traffic statistics and status messages.  You may type
^X to request that the current incoming file be cancelled, ^Z to request
that the entire incoming batch be cancelled, and ^C or ^E to return  im-
mediately to the Kermit-MS> prompt, exactly as described for the RECEIVE
command.


9.3.2. Commands for Connecting and Disconnecting

The CONNECT command connects your PC as a terminal to the remote system,
so that you can start up Kermit there.    The BYE, FINISH, and LOGOUT com-
mands allow you to shut down a remote Kermit server.

BYE        When  communicating with a remote KERMIT server, use the
        BYE command to shut down the server, log  out  its  job,
        and exit from Kermit-MS to DOS.

FINISH        Like BYE, FINISH shuts down the remote server.    However,
        FINISH    does not log out the server's job.  You are left
        at Kermit-MS prompt level so that you can  connect  back
        to the job on the remote system.

LOGOUT        The  LOGOUT command is identical to the BYE command, ex-
        cept you will remain at Kermit-MS prompt  level,  rather
        than exit to DOS, so that you can establish another con-
        nection.
                                       89


The CONNECT Command

Establish  an interactive terminal connection to the system connected to
the currently selected communications port (e.g.  COM1    or  COM2)  using
full duplex (remote) echoing and no parity unless otherwise specified in
previous  SET  commands.    Get  back  to Kermit-MS by typing the escape
character followed by the letter C. The escape character is Control-] by
default.

You can use the SET ESCAPE command to define a different escape  charac-
ter,  and  on some systems (including the PC and XT) you can SET BAUD to
change the baud rate, and SET PORT to switch between ports.

Terminal emulation is described in greater detail in section 9.4 below.


9.3.3. Commands for File Management

Kermit-MS provides commands or managing both local and remote files.


              THE REMOTE COMMANDS

The REMOTE keyword is a prefix for a number of commands.   It  indicates
that  the command is to be performed by the remote Kermit, which must be
running as a server.  Note that not all Kermit servers    are  capable  of
executing  all    these  commands,  and some Kermit servers may be able to
perform functions for which Kermit-MS does not yet have the  correspond-
ing  commands.    In case you send a command the server cannot execute, it
will send back a message stating that the command is unknown to it.   If
the  remote  server can execute the command, it will send the results to
your screen.  Here are the REMOTE commands which Kermit-MS may issue:

CWD [directory] Change Working Directory on the remote host.  Change the
        default source and destination area  for  file    transfer
        and  management.    You will be prompted for a password,
        which will be erased as you type it.    If  you  do  not
        supply    a  password  (i.e.  you  type  only  a    carriage
        return), the server will attempt to access the specified
        directory without a password.  If you do  not  supply  a
        directory  name,  your default or login directory on the
        remote system will be assumed.

DELETE filespec Delete the specified file or files on the remote system.
        In response, the remote host should display  a    list  of
        the files that were or were not successfully deleted.

DIRECTORY [filespec]  The remote system will provide a directory listing
        of the specified files.  If no files are specified, then
        all  files  in    the  default  area  (the current working
        directory) will be listed.

HELP        The remote  host  tells  what  server  functions  it  is
        capable of.

HOST [command]    Send  the command to the remote system's command proces-
                                       90


        sor for execution.

SPACE [directory]
        Provide  a  brief summary of disk usage in the specified
        area on the remote host.  If none specified, the default
        or current area will be summarized.

TYPE filespec    Display the contents of the  specified    remote    file  or
        files on the screen.


               THE LOCAL COMMAND

The  LOCAL  keyword  is a prefix for a number of commands.  It indicates
that the specified command is to be executed on the local MS-DOS system.
The LOCAL prefix may be omitted.  The local commands available are:

DELETE filespec Deletes the specified file or files.   As  in  DOS,  the
        names of the deleted files are not listed, only the mes-
        sage  "file(s)  deleted"  or "file(s) not found", and if
        you give the command "delete *.*", Kermit-MS will prompt
        "Are you sure?", like DOS.

DIRECTORY [filespec]  Lists the names,    sizes,    and  creation  dates  of
        files  that  match  the given file specification.  If no
        filespec is given, the command is equivalent to DIR *.*.

SPACE        Performs the  MS-DOS  CHKDSK  function    by  running  the
        CHKDSK    program  from  the current path, or default disk
        under DOS 1.1.

RUN filespec    Runs the specified file, which must be in .EXE    or  .COM
        format,  from  the  specified  path  or according to the
        value of the PATH variable if no path  was  included  in
        the  filespec.      This    command  requires  MS-DOS 2.0 or
        higher.

PUSH        Invokes an MS-DOS command processor  "under"  Kermit-MS,
        either    COMMAND.COM or whatever shell you have specified
        with COMSPEC.  When you return    to  Kermit-MS  (for  in-
        stance,  by  typing  the  MS-DOS EXIT command), you will
        find Kermit-MS as you left it, with all settings intact.
        This command only works in MS-DOS 2.0 or higher.

The local RUN command has various uses, one of which  is  to  supplement
the  features  of Kermit-MS.  For instance, suppose there is an involved
procedure that you regularly perform on a certain remote system --  this
might include giving commands to a modem to dial the system, looking for
a particular herald or prompt, performing a login command sequence, run-
ning a selected application, and then running Kermit to send the results
back  to your PC.  You could write a program in the compiled language of
your choice, say C or BASIC, to send the desired commands to your  modem
and  the  remote  system and to look for the appropriate responses.  You
could put all this in a Kermit-MS TAKE command file (see below), like
                                       91


  run update.com
  receive

The  program,  called UPDATE in this case, does everything up to and in-
cluding starting Kermit sending  from  the  remote  system.    When  the
program  terminates,  the next Kermit-MS command, "receive," is executed
from the command file.    When the end of the command file is reached, in-
teractive operation is resumed.


                THE TAKE COMMAND

Syntax: TAKE filespec

Execute Kermit commands from the specified file, which    may  include  an
explicit  path;  if no path is specified, the value of the PATH variable
is used; if PATH has no value, then the current disk and  directory  are
searched.  The command file may include TAKE commands, but it cannot in-
clude  characters  to be sent to a remote host during terminal emulation
(i.e. after a CONNECT command).  A command  file  may  include    comments
prefixed by semicolons.


                THE LOG COMMAND

Syntax: LOG filespec

Specifies  that all characters that appear on your screen during CONNECT
will be recorded in the specified file.  This allows  you  to  "capture"
files  from  a    remote    system    that  doesn't have Kermit, as well as to
record remote command typescripts.  The log is closed when you EXIT from
Kermit-MS or when you issue an explicit CLOSE command.


9.3.4. The SERVER Command

Kermit-MS is capable of acting as a Kermit server, providing file trans-
fer for users coming in through one of the  communication  ports.    The
current  version  of Kermit-MS can send files (the user on the other end
types the GET command), receive files (the user types  SEND),  and  ter-
minate, giving control back to the console (user types BYE).

To  put Kermit-MS into server mode, first issue any desired SET commands
to select and configure the desired port, and then type the SERVER  com-
mand.    Kermit-MS will await all further instructions from the user Ker-
mit on the other end of the connection, which may be hardwired    or  con-
nected through an autoanswer modem.  For example:

  Kermit-MS>set port 1
  Kermit-MS>set baud 1200
  Kermit-MS>set timer on
  Kermit-MS>set warning on
  Kermit-MS>server
                                       92


9.3.5. The SET Command

Syntax: SET parameter [value]

Establish  or  modify  various    parameters for file transfer or terminal
connection.  You can examine their values with the SHOW command.    Note
that  there  is  no  "set  ibm"  command;  IBM  mainframe  communication
parameters may be selected with a command macro (see below).   The  fol-
lowing SET commands are available in Kermit-MS:

        BAUD  Communications port line speed
        BELL  Whether to beep at the end of a transaction
    BLOCK-CHECK-TYPE  Level of error checking for file transfer
           DEBUG  Display packet contents during file transfer
    DEFAULT-DISK  Default disk drive for file i/o
     DESTINATION  Default destination device for incoming files
     END-OF-LINE  Packet terminator
         EOF  Method for determining or marking end of file
          ESCAPE  Escape character for CONNECT
    FLOW-CONTROL  Enable or disable XON/XOFF
       HANDSHAKE  Half-duplex line turnaround option
         HEATH19  Heath/Zenith-19 terminal emulation
      INCOMPLETE  What to do with an incompletely received file
         KEY  Specify key redefinitions, or "keystroke macros"
      LOCAL-ECHO  Specify which host does the echoing during CONNECT
          PARITY  Character parity to use
        PORT  Select a communications port
          PROMPT  Change the "Kermit-MS>" prompt to something else
         RECEIVE  Request remote Kermit to use specified parameters
          REMOTE  For running Kermit-MS interactively from back port
        SEND  Use the specified parameters during file transfer
       TAKE-ECHO  Control echoing of commands from TAKE files
           TIMER  Enable/disable timeouts during file transfer
         WARNING  Specify how to handle filename collisions

The SET commands that are peculiar to MS-DOS Kermit are now described in
greater detail.  The others behave as in "ideal" Kermit.


SET BAUD

Syntax: SET BAUD rate

Set  the  speed  of  the currently selected terminal communications port
(COM1 by default) to 300, 1200, 1800, 2400, 4800, 9600 or  other  common
baud  rate.    Some implementations do not support this command.  In any
case, Kermit-MS leaves the current communication port settings alone un-
less you issue explicit SET commands to change them.


SET BELL

Syntax: SET BELL ON or OFF

Specifies whether bell (beeper) should sound upon completion of  a  file
transfer operation.
                                       93


SET DEBUG

Syntax: SET DEBUG ON or OFF

ON    Display  the  Kermit  packet  traffic on your screen during file
    transfer.  If the debugger is loaded,  transfer  control  to  it
    when CTRL-C is typed.  In Heath-19 terminal emulation on the IBM
    PC, display unusual control characters in uparrow notation.

OFF    Don't  display  debugging information (this is the default).  If
    debugging was in effect, turn it off.


SET DEFAULT-DISK

Syntax: SET DEFAULT-DISK x:

Specify the default disk drive to use for file transfer, directory list-
ings, and so forth.  Equivalent to typing the DOS command  for    changing
disks.


SET DESTINATION

Syntax: SET DESTINATION device

Specify the device for incoming files, DISK or PRINTER.  SET DESTINATION
PRINTER will cause incoming files to be spooled directly to the printer.
The normal destination is DISK.


END-OF-LINE

Syntax: SET END-OF-LINE number

If  the  remote  system needs packets to be terminated by anything other
than carriage return, specify the decimal value  of  the  desired  ASCII
character.


SET EOF

Syntax: SET EOF option

Controls how the end of file is handled.  The options are:

CTRL-Z        Append    a  Control-Z character to the end of an incoming
        file, unless it already ends with a Control-Z.     Certain
        MS-DOS text editors and other applications require files
        to  be    in  this  format.  For outbound files, treat the
        first Control-Z as the end of file, and do not    send  it
        nor any characters following it.

NOCTRL-Z    (Default)  Store  incoming files exactly as is, and send
        MS DOS files exactly as  is  (according  to  their  byte
        count).
                                       94


SET ESCAPE

Syntax: SET ESCAPE character

Specify  the  control  character you want to use to "escape" from remote
connections back to Kermit-MS.    The default  is  normally  ^]  (Control-
Rightbracket).    The  character is entered literally, and should normally
be chosen from the ASCII control range.


SET FLOW-CONTROL

Syntax: SET FLOW-CONTROL option

Specify the full duplex  flow  control    to  be    done  on  the  currently
selected  port.    The    current  options  are  XON/XOFF  and  NONE.  The
specified type of flow control will be done during both terminal  emula-
tion  and file transfer.  If set to XON/XOFF, HANDSHAKE is automatically
set to OFF.


SET HANDSHAKE

Syntax: SET HANDSHAKE option

Specify any half-duplex handshaking to be done on the currently selected
port.  The options are BELL, CR, LF, NONE, XOFF, or XON.  The  specified
handshaking will be done during file transfer only.  If HANDSHAKE is set
to anything other than NONE, FLOW-CONTROL is automatically set to OFF.


SET HEATH19

Syntax: SET HEATH19 ON or OFF

Specify  whether Kermit-MS should use its built-in software facility for
emulating a Heath/Zenith-19 (H19) terminal.

ON    During CONNECT, incoming characters are to be examined    for  H19
    terminal  screen control commands (escape sequences), and if en-
    countered, the commands are to be emulated  on    the  PC  screen.
    The  H19  codes are a superset of the popular DEC VT52 codes, so
    if your system does not support the Heath-19, you  may    tell  it
    that  your  terminal  type  is    VT52  (or  one    of the many VT52
    compatibles).  The Heath-19 codes are listed  in  section  9.10,
    below.

OFF    All  incoming  characters  will  be  sent  to the screen "bare",
    through DOS.  If you have loaded a device driver  into    DOS  for
    the CON: device, such as ANSI.SYS, then that driver will be able
    to  interpret  the codes itself. Most non-IBM systems have their
    own screen control code interpreter built into DOS or  firmware,
    or available as a loadable device driver.

See section 9.4 for details about terminal emulation.
                                       95


SET KEY

Syntax: SET KEY key-specifier

Specifies  that when the designated key is struck during terminal emula-
tion, the associated character string is sent.    The key-specifier is one
of the keywords F1, F2, ..., or SCAN followed by a scan code.     Systems
that have a BACKSPACE key also include BACKSPACE as a keyword.

If SCAN is used, it is followed by a decimal number to indicate the scan
code  of  the  key, which you would ascertain from your system reference
manual, or else by using the  Kermit-MS  SHOW  KEY  command.    SET  KEY
prompts  you  on  a new line for the definition string.  Certain charac-
ters, like ESC and CR, may not be entered literally into the string, but
can be included by inserting escape codes of the form \ooo, a  backslash
followed  by  a  2-  or  3-digit octal number corresponding to the ASCII
value of the desired character.  If some other key redefinition package,
like  ProKey,  has  been  loaded,  then  its  redefinitions  will   take
precedence over Kermit's.

The  SET  KEY  command is illustrated in the terminal emulation section,
9.4, below.


SET LOCAL-ECHO

Syntax: SET LOCAL-ECHO option

Specify how characters are echoed during terminal emulation on the  cur-
rently    selected port.    ON specifies that characters are to be echoed by
Kermit-MS (because neither the remote computer    nor  the  communications
circuitry  has    been  requested  to  echo), and is appropriate for half-
duplex connections.  LOCAL-ECHO is  OFF  by  default,  for  full-duplex,
remote echo operation.

When  you SET LOCAL-ECHO ON, the current HANDSHAKE (if any) is automati-
cally enabled and full-duplex FLOW-CONTROL is automatically turned  off.
When you SET LOCAL-ECHO OFF, HANDSHAKE is also disabled, and the current
mode  of  FLOW-CONTROL    (if  any)  is  enabled.  If this behavior is un-
desired, you may override it by typing explicit  SET  HANDSHAKE  or  SET
FLOW commands after entering the SET LOCAL-ECHO command.


SET PARITY

Syntax: SET PARITY keyword

Specify  the character parity to be used on the currently selected port.
The choices for SET PARITY are NONE (the default), ODD, EVEN, MARK,  and
SPACE.    NONE means no parity processing is done, and the 8th bit of each
character can be used for data when transmitting binary files.

You  will  need to SET PARITY to ODD, EVEN, MARK, or possibly SPACE when
communicating with a system, or over a network, or through modems,  con-
centrators, multiplexers, or front ends that require or impose character
parity    on  the  communication line.  For instance, GTE Telenet requires
                                       96


MARK parity.  If you neglect to SET PARITY when the communications equi-
pment requires it, the symptom may be that terminal emulation works par-
tially, and file transfer does not work at all.

If you have set parity to ODD, EVEN, MARK, or SPACE, then Kermit-MS will
request  that  binary files will be transferred using 8th-bit-prefixing.
If the other side knows how to do 8th-bit-prefixing (this is an optional
feature of the KERMIT protocol, and not all  implementations  of  KERMIT
have it), then binary files can be transmitted successfully.  If NONE is
specified,  8th-bit-prefixing will not be requested.  Note that there is
no advantage to using parity; it only slows Kermit file  transfer  down.
The  SET  PARITY  command  is  provided only to allow Kermit to adapt to
hardware that insists upon using parity.


SET PORT

Syntax: SET PORT number

On machines with more than one communications port, select the    port  to
use  for  file    transfer  and CONNECT.    This command lets you use a dif-
ferent asynchronous adapter, or switch between two or more  simultaneous
remote    sessions.    Subsequent  SET  BAUD, PARITY, HANDSHAKE, FLOW, and
LOCAL-ECHO commands will apply to this port only.  SET    PORT  1  selects
COM1, SET PORT 2 selects COM2.


SET REMOTE

Syntax: SET REMOTE ON or OFF

If  you  wish  to run Kermit-MS interactively through the back port, for
instance after the operator has done CTTY COM1, you must give  the  com-
mand SET REMOTE ON; this suppresses the file transfer display screen, so
that the display won't interfere with the file transfer itself.


SET RECEIVE

Syntax: SET RECEIVE parameter value

At  the  beginning of a protocol operation, request the remote Kermit to
use the given value specified parameter, or inform  Kermit-MS  that  the
remote Kermit will be using it.

PACKET-LENGTH    Ask  the  remote  Kermit  to  use  the specified maximum
        length for packets that it sends to Kermit-MS.    The nor-
        mal (and maximum) length is 94.   Use  this  command  to
        shorten packets if the communication line is noisy; this
        will  decrease    the probability that a particular packet
        will be corrupted, and will  reduce  the  retransmission
        overhead  when    corruption  occurs, but it will increase
        the protocol overhead.

PADCHAR     Ask the remote Kermit to use the given character for in-
        terpacket padding.  Kermit-MS should never  require  any
                                       97


        padding.

PADDING     Ask the remote Kermit to insert the given number of pad-
        ding  characters  before  each    packet    it  sends.  This
        should never be necessary.

START-OF-PACKET The remote Kermit will be marking the beginning of pack-
        ets with something other than Control-A.  This    will  be
        necessary  only  if the hosts or communication equipment
        involved cannot pass a Control-A through as data.

TIMEOUT     Ask the remote Kermit to time out after the given number
        of seconds if a packet expected from Kermit-MS    has  not
        arrived.   Use this command to change the normal timeout
        interval.


SET SEND

Syntax: SET SEND parameter value

PACKET-LENGTH    Use the specified maximum length for  outbound    packets.
        Normally,  Kermit-MS uses whatever length the other Ker-
        mit requests.

PADCHAR     Use the specified  character  for  interpacket    padding.
        Some hosts may require some padding characters (normally
        NUL or DEL) before a packet.

PADDING     How many padding characters to use between packets, nor-
        mally zero.

QUOTE        Use  the  indicated  printable    character  for prefixing
        (quoting) control characters and  other  prefix  charac-
        ters.  The only reason to change this would be for send-
        ing a very long file that contains very many "#" charac-
        ters (the normal control prefix) as data.

START-OF-PACKET Mark the beginning of outbound packets with some control
        character  other than Control-A.  This will be necessary
        only if the remote host or the communication channel in-
        volved cannot accept a Control-A as data.    The  remote
        host  must have been given the corresponding SET RECEIVE
        START-OF-PACKET command.

TIMEOUT     Change Kermit-MS's normal timeout interval; this command
        is effective only if TIMER is set to be ON; it    is  nor-
        mally    OFF  so  that  the  remote  KERMIT  can  control
        timeouts.
                                       98


SET TAKE-ECHO

Syntax: SET TAKE-ECHO ON or OFF

Specifies  whether  screen  display  should occur during implicit or ex-
plicit TAKE operations on MSKERMIT.INI or other Kermit-MS command files,
and during evaluation of macro definitions.  Handy for finding errors in
command files.


SET TIMER

Syntax: SET TIMER ON or OFF

Enable or disable the timer that is used during file transfer  to  break
the  deadlock  that  occurs when an expected packet does not arrive.  By
default, the timer is OFF, because Kermit-MS is usually used in conjunc-
tion with a mainframe that is doing its own timeouts.     During  a  file
transfer,  it  is  sufficient  for one side to do the timing out and the
mainframe is usually better equipped to adjust timeout    intervals  based
on  system  load or other conditions.  The timer should be set ON if you
are communicating with a system that cannot do    timeouts,  such  as  IBM
VM/CMS Kermit.


SET WARNING

Syntax: SET WARNING option

Specify  what to do when an incoming file has the same name as an exist-
ing file in the default directory of the default device.  If ON,  Kermit
will  warn  you  when  an incoming file has the same name as an existing
file, and automatically rename the incoming file (as  indicated  in  the
warning  message) so as not to destroy (overwrite) the pre-existing one.
If OFF, the pre-existing file is destroyed, even if  the  incoming  file
does not arrive completely.


9.3.6. The SHOW Command

Syntax: SHOW option

Currently,  most  parameters  that  may be altered with SET commands are
displayed by the STATUS command.  The SHOW command is used for    display-
ing macro definitions and key redefinitions.

The  SHOW  MACROS  command  displays  the  definitions    of all currently
defined macros.

The SHOW KEY command allows you to determine the scan code  produced  by
pressing  a  given  key,  so that you can construct a SET KEY command to
redefine the key.  If the key already has a redefinition in effect, that
too will be displayed.    In this example, a DEC Rainbow    user  determines
the  scan  code for the accent grave key, and then redefines that key to
send ESC:
                                       99


  Kermit-MS>show key
  Press a key: `
    Scan Code:    96
    Definition:
  Kermit-MS>set key scan 96
  Definition string: \33
  Kermit-MS>show key
  Press a key: `
    Scan Code:    96
    Definition: \33
  Kermit-MS>

The SHOW KEY command only works on certain systems.


9.3.7. Command Macros

Kermit-MS  provides  a    facility  for  combining commands into "macros."
Command macro definitions may be included  in  your  MSKERMIT.INI  file,
TAKEn  explicitly from a specified file, or typed interactively, and may
be invoked with the DO command.


               THE DEFINE COMMAND

Kermit-MS command macros are constructed with the DEFINE command.    The
syntax is

  DEFINE macro-name  [command [, command [, ...]]]

Any Kermit-MS commands may be included.  Example:

  define telenet set parity mark, set baud 1200, connect


                 THE DO COMMAND

A  Kermit-MS  command  macro  is  invoked using the DO command.  For in-
stance, Kermit-MS comes with a    predefined  macro  to  allow  convenient
setup for IBM communications; to invoke it, you would type

  do ibm

The  IBM macro is defined as "parity mark, handshake xon, local-echo on,
timer on".  You can delete or replace this definition by  adding  a  new
(perhaps null) definition, such as

  define ibm parity even, handshake cr, local-echo on, timer on

or

  define ibm
                                      100


9.4. Terminal Emulation

When you issue the CONNECT command, your PC acts as a terminal connected
to  a  remote computer through the currently selected port.  The charac-
ters you type are sent out the port, and characters that arrive  at  the
port  are displayed on your screen.  If you have not previously issued a
SET PORT command, COM1 is used.  If you have SET LOCAL-ECHO ON    for  the
selected  port,  then Kermit-MS will display characters on the screen as
you type them.    If LOCAL-ECHO is OFF, then XON/XOFF flow control will be
done unless you have SET FLOW-CONTROL OFF.  If you have  SET  PARITY  to
anything  other  than NONE, Kermit-MS will add the appropriate parity to
each outbound character, and strip any parity from incoming ones.  While
CONNECTed, you can also communicate with an autodialer or "smart  modem"
to  control  the  communications line, hang it up, and the like; for in-
stance, typing +++ to a Hayes-like modem will allow you to  follow  that
by dialing or hangup commands.

If  Heath-19  emulation  is  being  done,  incoming  characters  will be
monitored for H19/VT52 escape sequences.  These will be interpreted  ac-
cording  to the table in section 9.10.    In addition, keys on the numeric
keypad will send H19/VT52 sequences unless you disable this  feature  in
some  way,  for instance by pressing Num Lock on the IBM PC keyboard, or
with key redefinitions.

    Caution: On some systems, such as the IBM PC and  XT,  Kermit-MS
    accesses  the  screen  memory memory directly to perform certain
    H19 emulation functions  such  as  character  insert/delete  and
    screen scroll.  Without direct screen memory access, these func-
    tions  would  be  painfully  slow.     Although Kermit-MS has been
    tested successfully on a variety of monochrome and    color  adap-
    ters  and  monitors,  there  may  be combinations for which this
    method could cause video problems, such as snow.    Should    this
    occur,  you  can alleviate the problem by setting HEATH19 emula-
    tion OFF.  In that    case,  however,  you  remove  not  only  the
    problems,  but  also  the  desirable features of emulation.  But
    Kermit-MS does permit you to load  an  external  console  device
    driver,  such  as  IBM's ANSI.SYS, to provide any desired screen
    control.

Here are the terminal emulation options for the systems  presently  sup-
ported by Kermit-MS:

  System     EscChar   Cabilities    Terminal Service
  IBM PC, XT       ^]       R M P K    Heath19 emulation
  DEC Rainbow       ^]       R   P K    VT102 firmware
  HP-150       ^]       R        HP-2623 firmware
  Wang PC       ^A            Wang firmware
  Generic DOS       ^]            Depends on system

Under Capabilities, R means rollback, M means mode line, P means printer
control, and K means key redefinition.

IBM PC/XT Kermit can disable Heath-19 emulation and use an external con-
sole device driver like ANSI.SYS instead.

When you first issue the CONNECT command, a message (on some systems, an
                                      101


inverse  video    "mode line") will display the most important facts about
the connection you've just established, so that you can quickly diagnose
any problems.  The items displayed in the mode line include  the  escape
character,  port number, the baud rate, the parity, the echo, and how to
get help, for instance:

+---------------------------------------------------------------------+
|EscChar:^],Port:1,Baud:9600,Parity:None,Echo:Remote,Type ^]? for Help|
+---------------------------------------------------------------------+

The escape character is used to regain the attention of Kermit-MS.  When
you type the escape character, Kermit-MS waits for you to follow it with
a single character command.  For instance, the    single-character-command
"?"  produces  a  list  of  available single character commands, such as
this:

  ?   Help -- prints the available single-character commands.
  C   Close the connection and return to Kermit-MS prompt level.
  S   Show the status of the connection.
  B   Send a BREAK signal to the port.
  0   (the digit zero) Send a NUL (ASCII 0) to the port.
  Q   Temporarily quit logging the remote session.
  R   Resume logging the remote session.
  M   Toggle the mode line, i.e. turn it off if it is on & vice versa.
  ^]  (or whatever you have set the escape character to be)
      Typing the escape character twice sends one copy of it to the con-
      nected host.

Typing any other character (except the space bar,  which  is  the  "null
command")  after  the escape character will cause Kermit-MS to beep, but
will do no harm.  The escape character can be changed to something other
than Control-Rightbracket by using the SET ESCAPE command.

Kermit-MS includes several advanced features  for  use    during    terminal
emulation,  including  screen scroll, printer control, and key redefini-
tions.


Screen Scroll

Kermit-MS provides several pages of screen memory, which may be scrolled
up and down using keys as follows:

  Function          IBM PC/XT   Rainbow        HP-150
  Screen Down          PgDn      PrevScreen        Prev
  Line Down          Ctrl-PgDn   Ctrl-PrevScreen   Shift-UpArrow
  Screen Up          PgUp      NextScreen        Next
  Line Up          Ctrl-PgUp   Ctrl-NextScreen   Shift-DownArrow
  Top of Memory       Home
  Bottom of Memory    End

There is presently no way to assign these functions to other keys.
                                      102


Printer Control

A  locally  attached  printer may be controlled in the normal manner, on
most systems.  Pushing the "Print Screen" key (shifted on some  systems)
will  cause the current contents of the screen to be printed or spooled;
holding down CTRL while depressing Print Screen will start or  stop  the
spooling  of  incoming    characters to the printer.  ^P or ^N are sent to
the host during terminal emulation, and do not toggle printing, as  they
do when you're talking directly to DOS.

CTRL-Print-Screen  can be simulated with the Kermit-MS LOG PRN and CLOSE
commands.


Key Redefinitions

Key redefinitions are useful for defining "keystroke  macros"  of  login
sequences,  frequently issued commands, and so forth, and for setting up
the terminal for use with host resident software designed to  work  with
terminals  that send predefined sequences from their function keys.  For
instance, here's a key redefinition file for arranging the  DEC  Rainbow
keyboard into the normal ASCII keyboard layout:

  ; Make shift-comma send a left angle bracket
  set key scan 556
  <
  ; Shift-period sends a right angle bracket
  set key scan 558
  >
  ; Accent grave is where ESC is supposed to be
  set key scan 96
  \33
  ; Put accent grave on the ESC function key
  set key f11
  `

The  SET  KEY  facility may be used provide the PC with a "meta" key for
use with editors like EMACS or TVEDIT that can use "meta characters"  as
commands.   A meta key is a shift key whose effect is to turn on the 8th
(parity) bit of the character.    For instance, on the  IBM  PC  the  scan
codes  produced  by  holding  down  ALT  together with other keys can be
determined using SHOW KEY, and then 8-bit ASCII equivalents with the 8th
bit turned on can be defined using SET KEY; if the scan code produced by
typing ALT-a, i.e. the letter "a" (ASCII 141, octal) with  the  ALT  key
held  down,  is  2078  (decimal),  you    would set the META equivalent to
141+200=341 (octal), or "\341" in octal SET KEY notation:

  Kermit-MS>sho key
  Press a key: ALT-a
    Scan Code: 2078
    Definition:
  Kermit-MS>set key scan 2078
  Definition String: \341

Whenever you type ALT-a with this definition in effect,  Kermit-MS  will
transmit octal 341, rather than 141.
                                      103


9.5. Installation of Kermit-MS

         by Bill Catchings, Columbia University

If you already have Kermit on your PC, you can use it to obtain new ver-
sions  of Kermit-MS when they appear on the central system at your site.
If you do not have Kermit or any other reliable file capture facility on
your PC, and there is no one from whom you can borrow a floppy    disk  to
copy  Kermit,  then  you  should read the following instructions for in-
itially "bootstrapping" Kermit-MS from a mainframe where  it  is  stored
onto your microcomputer.

There  are  at    least  three methods of initially getting Kermit-MS onto
your PC:

   1. Try again to find a copy on diskette.

   2. Use another file capture facility to get it.

   3. Type in and run a bootstrapping program.


9.5.1. Try Again To Find A Kermit Disk

Before explaining how to bootstrap Kermit onto    your  PC,  a  disclaimer
must  be made.    Although a fair amount of thought and time has gone into
these procedures, they are far from error free.  If they were foolproof,
there would be no need for a protocol such as Kermit.    There  are  many
places    where  things can go wrong, from something as simple as a typing
mistake to something as unavoidable and probably inevitable  as  a  com-
munications  line  failure.   By far the easiest and best way to install
Kermit is from a floppy disk.  Before you embark on any of the following
procedures it is a good idea to check once again for a diskette to copy,
even it it contains an old version  of    Kermit.    The    time  you  spend
searching  is  likely to be far less frustrating than the time you spend
trying to bootstrap Kermit by the methods described below.


9.5.2. Bootstrapping From the Communication Line

If you can't find a diskette with Kermit on  it,  there  are  two  other
methods  available  for  bootstrapping    MS-DOS Kermit onto your PC.  The
first method is to use a file capture  method  or  other  file    transfer
protocol  to  transfer    the file to your PC.  Some systems come supplied
with facilities like this,  and  various  public  domain  or  commercial
packages  are available.  The second method requires you to type in your
own downloading program.

In either case, you must transmit the file  from  the  system  where  it
resides  over a communication line and into your PC.  Since version 2 of
MS-DOS Kermit is much larger  than  version  1,  it  comes  with  a  new
bootstrapping  procedure in which the executable program is encoded much
more compactly than in the earlier "fix" files.  The new encoding  packs
3 .EXE file bytes into 4 printable characters in the MSxxx.BOO file, and
also compresses adjacent zero bytes (of which there are many).    The .BOO
file  contains only printable characters, to ensure that downloading can
                                      104


take place regardless of parity or other peculariaries of the communica-
tion channel.


9.5.2.1. Use An Existing File Capture Facility

In  the rest of this discussion of bootstrapping, the host-resident boot
.BOO file will be referred to as MSKERMIT.BOO.    In fact, the actual name
will depend on which MS-DOS system you are using -- MSIBMPC.BOO for  the
IBM PC or XT, MSRB100.BOO for the Rainbow 100, etc.

Use  your  file  capture  facility,  whatever it may be, to get the file
MSKERMIT.BOO onto your PC's disk, but first make sure  you  have  enough
room  for  it.      Once    the file is on your disk, you must run the BASIC
program MSPCTRAN.BAS to decode the file  back  into  KERMIT.EXE.    This
program can be downloaded by the same method you used with MSKERMIT.BOO.
The  program  looks  on  your  current    disk  and directory for the file
MSKERMIT.BOO and outputs KERMIT.EXE to the same place.      KERMIT.EXE  is
about 80K bytes, so make sure there is space for it on your disk or else
you  will  have  to start the program over.  Since the program will take
about twenty minutes to completely translate the file you will    want  to
avoid running it more than once.


9.5.2.2. Type In Your Own Bootstrap

If  you  can't  find  some  method for downloading the .BOO file and the
BASIC program, the second way of bootstrapping    Kermit    is  to    use  the
programs   MSPCBOOT.BAS   and  MSBOOT.FOR  to  download  via  your  PC's
asynchronous port from your host and  translate  it  directly,    "on  the
fly."    You  run  the  program MSBOOT.FOR on your host and then run the
program MSPCBOOT.BAS in BASIC on your PC.  The FORTRAN program sends the
encoded .EXE file to the BASIC program, which decodes it and  stores  it
in  executable    form  on  your    current directory as KERMIT.EXE.  A very
rudimentary form of error checking is done to allow obviously  corrupted
records to be retransmitted.  Follow this procedure:

   1. First,  you  must  establish a connection from your PC to the
      host system.   A    high  speed  connection  is  preferable;  a
      "clean"  line is preferable to a noisy one.  In fact, a clean
      line is essential for this procedure.  You must  be  able  to
      log  in  to the host system over this connection.  If your PC
      already has a terminal emulation facility, use that.  If not,
      you might need to put your PC next to a real terminal and use
      that for logging in, then switch the connector to the  PC  at
      the  crucial  moment.  If you are using a terminal, make sure
      the terminal and PC have their communication ports set to the
      same speed.

   2. Ensure that the files MSBOOT.FOR and MSKERMIT.BOO are present
      on the host system.  MSBOOT.FOR is listed below, in case    you
      need to type it in.

   3. Get  back  to  your PC and type in MSPCBOOT.BAS on your PC; a
      listing appears below.  There is no need to type in the  com-
      ments (anything following an apostrophe); they are only there
                                      105


      to  clarify  what the program is doing.  Check very carefully
      for errors.  You should check line 80 in the program  to    see
      that  it reflects the way your system is actually set up.  If
      necessary, substitute the correct baud rate for the  supplied
      rate of 9600, and if you are not using COM1: make that change
      as  well.   If you are downloading from an IBM or other half-
      duplex mainframe,  leave    line  1000  as    it  is;  otherwise,
      replace it by a RETURN statement.  If you type it in directly
      to BASIC make sure you save the program before you run it, so
      you won't have to type it in again in case of error.

   4. Get  back  to  your host system and compile MSBOOT.FOR, if it
      needs compiling.    Define logical unit numbers 5 and 6  to  be
      the  controlling    terminal, and logical unit 7 to be the file
      MSKERMIT.BOO.  On VAX/VMS systems,  for  example,  use  these
      commands:

    $assign sys$input for005
    $assign sys$output for006
    $assign mskermit.boo for007

      On a DECSYSTEM-20, do:

    @define 5: tty:
    @define 6: tty:
    @define 7: mskermit.boo

      On a DECsystem-10, do something like this:

    .assign tty: 5:
    .assign tty: 6:
    .assign dsk: 7:
    .rename for007.dat=mskerm.boo

      On an IBM system under VM/CMS, do this:

    .filedef 5 term ( lrecl 80 recfm v
    .filedef 6 term ( lrecl 80 recfm v
    .filedef 7 disk mskermit boo ( lrecl 77 recfm f perm

   5. Set your host system up for downloading:

     - Ensure  that  your terminal does not automatically pause
       at the end of a screenful of output.  For instance, on a
       DEC-20 you would issue the command  "terminal  no  pause
       end-of-page".

     - Do  whatever  you can to disable messages from appearing
       at your terminal while these programs are running.  This
       would include messages from other users, mail  notifica-
       tion,  alarms  or alerts, system messages, and so forth.
       Such messages will interfere  with  the  procedure,    and
       probably render the result useless.

     - You    should    put  your  host terminal in "local echo" or
       "half duplex" mode, if possible.
                                      106


   6. Start the MSBOOT program on your host system.

   7. Get  back  to  the  PC.     If you have been using a terminal,
      switch the connector to the PC.

   8. Now run the BASIC program, MSPCBOOT.BAS.    This procedure will
      take at least twenty minutes and possibly longer depending on
      line speed.  Watch your modem and/or disk  lights  for  reas-
      surance that something is happening.

By  using one of these installation methods, you should now have a work-
ing version of Kermit.    If you experience any  problems  or  quirky  be-
havior    with  the  program,  it's possible that some part of it was cor-
rupted during the downloading procedure.   Perhaps  enough  usable  code
remains  to  allow  you to transfer MSKERMIT.EXE from the host.  If not,
you will have to repeat the downloading procedure.

Once you have Kermit-MS on your disk, you should make the disk available
to other users for copying, so that they can be  spared  the  tedium  of
this bootstrap procedure.

Here  is  a  listing  of MSPCBOOT.BAS.    The "outdented" PRINT statements
with line numbers ending in 5 may  be  included  if  you  want    incoming
records  to  be  displayed on the screen.  You don't need to include the
comments.

1    'Run this program on the PC in conjunction with a Fortran program
2    '(MSBOOT.FOR) on the mainframe to download Kermit to the PC.  This
3    'program will run for about thirty minutes, depending on line speed.
4    ' Bill Catchings, June 1984
5    ' Columbia University Center for Computing Activities

10   t$ = time$             ' Save the time.
20   defint a-z             ' All integer to gain some speed.
30   n$ = chr$(0)
40   z = asc("0")
50   t = asc("~")-z
60   def fnuchr%(a$)=asc(a$)-z
70   open "com1:9600,s,7,1,cs,ds,cd" as #1

100  print#1,"O ,"                      ' Char constants "O", " " and ","
110  input#1,f$
120  if len(f$) < 5 then goto 110    ' In case the host echos the ACK.
130  input#1,n
135 print f$+" "+str$(n)
140  if n > 20 then goto 900
150  open f$ for output as #2
160  print "Outputting to "+f$
170  goto 300                ' Correct version of the file.

200  gosub 1000             ' Do turnaround char processing
210  print#1,"NO"                       ' Tell host data was incorrect.
220  goto 320
                                      107



300  gosub 1000             ' Do turnaround char processing
310  print#1,"OK"                       ' Say the line was all right.
320  input#1,x$
330  if len(x$) < 5 then goto 320    ' In case the host echos ACK/NAK
340  input#1,n
345 print x$+" "+str$(n)
350  if len(x$) <> n then goto 200    ' Length doesn't match, NAK it.
360  if x$ = "&&&&&&&&&&" then goto 800 ' End of file?
370  y$ = ""                            ' Set output string to null.
380  goto 500

400  print#2,y$;            ' Print the output string.
410  goto 300                ' Go get another line.

500  if len(x$) = 0 goto 400        ' Done with input string?
510  a = fnuchr%(x$)
520  if a = t then goto 700        ' Null repeat character?
530  q$=mid$(x$,2,3)            ' Get the quadruplet to decode.
540  x$=mid$(x$,5)
550  b = fnuchr%(q$)
560  q$ = mid$(q$,2)
570  c = fnuchr%(q$)
580  q$ = mid$(q$,2)
590  d = fnuchr%(q$)

600  y$ = y$ + chr$(((a * 4) + (b \ 16)) and 255) ' Decode the quad.
610  y$ = y$ + chr$(((b * 16) + (c \ 4)) and 255)
620  y$ = y$ + chr$(((c * 64) + d) and 255)
630  goto 500                ' Get another quad.

700  x$ = mid$(x$,2)            ' Expand nulls.
710  r = fnuchr%(x$)            ' Get the number of nulls.
715 print " Null: ",r
720  x$ = mid$(x$,2)
730   for i=1 to r            ' Loop, adding nulls to string.
740   y$ = y$ + n$
750   next
760  print#2,y$;            ' Print the nulls.
770  y$ = ""                            ' Clear the output buffer.
780  goto 500

800  print "Processing complete, elapsed time: "+t$+" to "+time$
810  print "Output in "+f$
820  close #1,#2
830  goto 9999

900  print "?The format of the BOO file is incorrect"
910  goto 820

1000 x$ = input$(1,#1)        ' Make this line RETURN for full-duplex
1010 if x$ <> chr$(17) then goto 1000    ' Loop for a turn around char.
1020 return

9999 end
                                      108


Here  is a listing of MSBOOT.FOR, in case you can't find it on your host
system:

C     This Fortran program should be run on the mainframe in conjunction
C     with a Basic program (MSPCBOOT.BAS) on the PC to transfer
C     MSKERMIT.BOO to the PC and translate it into KERMIT.EXE.    This
C     program uses a very rudimentary technique to try to insure that
C     the characters it sends arrive correctly.  It just sends a count
C     of the number of characters sent after each line.  In this way any
C     errors of character loss or insertion will be caught.  If a
C     character is just corrupted it will not be caught.  Hopefully if
C     this happens it will be in a non-critical part of the KERMIT.EXE
C     file.  The reason a simple checksum was not used was so that this
C     program could run on machines using either EBCIDIC or ASCII
C     characters.  This program should take about thirty minutes to run.

C     This program assumes that 5 and 6 are directed to the terminal and
C     7 is directed to the file MSKERMIT.BOO.

      INTEGER LINE(77), ACK(4), CHECK, OK, SPACE, COMMA

      WRITE(6,100)
100   FORMAT(' Ready to transfer data, now run MSPCBOOT.BAS on the PC.')

C     Get characters for constants (character constants are rough in
C     some FORTRANs!)
      READ (5,200) OK, SPACE, COMMA, ACK
200   FORMAT(4A1)
      GO TO 30

C     Get terminal handshake.
10    READ (5,200)ACK

C     Did the other side like it?  (Did they send OK?)
      IF (ACK(1) .NE. OK) GO TO 50

C     Yes, get new line from file.
20    READ (7,300,END=99)LINE
300   FORMAT(77A1)

C     Count the characters as some rudimentary check for noise.
      I = 1
30    IF (LINE(I) .EQ. SPACE) GO TO 40
      I = I + 1
      GO TO 30

C     Put in a comma followed by the count.
40    LINE(I) = COMMA

C     Write to TTY.
50    WRITE (6,400)LINE,I-1
400   FORMAT(' ',77A1,I2)
      GOTO 10
                                      109



C     Send good-bye message.
99    WRITE (6,500)
500   FORMAT(' ',10('&'),',10')

      STOP
      END


9.6. Compatibility with Older Versions of MS-DOS Kermit

MS-DOS    Kermit    supports  many    different systems.  Like CP/M-80 KERMIT,
this support was added to the program piecemeal, at  many  sites,  using
conditional assembly.  However, before allowing the program to grow into
a  complicated    monolith like CP/M-80 KERMIT, we have broken the program
up into separate modules,  with  system  dependencies  isolated  into  a
single    module consisting of compact collections of low-level primitives
for console and port i/o.

The last monolithic (single source file) release of  MS-DOS  Kermit  was
1.20.     To this and earlier versions was added support for systems like
the Seequa Chameleon, the Tandy 2000, the Victor 9000, the  Heath/Zenith
100,  and  others.    Eventually,  support  for these systems may be in-
tegrated with the new modular version.    Meanwhile, implementations based
on these old versions will have at least the  following  incompatibilies
from the version described here:

   - RECEIVE filespec is used instead of GET filespec.    There is no
     GET  command  in  older  versions, and no way to specify a new
     name for an incoming file.
   - No LOCAL or REMOTE commands.
   - No 8th-bit  prefixing,  repeat  counts,  CRCs  or    2-character
     checksums.
   - No TAKE or initialization files.
   - No command macros or command line arguments.
   - No terminal session logging.

and others, depending on the specific version.


9.7. What's Missing

Kermit-MS  has plenty of room for improvement.    Features that need to be
improved or added include:

   - A built-in facility for sending files "raw" to the remote sys-
     tem, obeying current settings for parity, flow control,  hand-
     shake,  and so forth.  This might include a script interpreta-
     tion  facility  to  allow    remote    sessions  to  be  conducted
     automatically.  For the present, this can be accomplished with
     a    user-supplied  program    invoked with the Kermit-MS RUN com-
     mand.

   - Additional  functionality    when   running     in   server   mode
     --  directory  listings,  file deletion, execution of DOS com-
     mands, etc.
                                      110


   - More commands when talking to remote servers -- REMOTE RENAME,
     COPY, STATUS, WHO, etc.

   - Filename  conversion  options  (normal form, handling of fully
     qualified filespecs, etc.).

   - Transaction file logging.

   - Improved command parsing; for instance, accept default  values
     for omitted trailing fields.

   - A better built-in help facility.

   - Support for Kermit file attribute packets.

   - The Kermit-MS program is quite large.  Much of the size is due
     to  the deliberate decision to provide support for versions of
     MS-DOS prior to 2.0.  At some point, this    support  should  be
     removed.     This  will not only reduce the size of the program
     considerably, but also provide much more flexibility.


9.8. Program Organization

Kermit-MS version 2 is composed of separate assembler source files,  as-
sembled separately, and linked together.  The modules are:

System/Device Independent:

    MSKERM.ASM      Main program
    MSSEND.ASM      File sender
    MSRECV.ASM      File receiver
    MSSERV.ASM      Server operation
    MSFILE.ASM      File i/o
    MSCMD.ASM      Command parser
    MSTERM.ASM      CONNECT command
    MSCOMM.ASM      Communications port buffering & flow control
    MSSET.ASM      SET, SHOW, and STATUS commands
    MSDEFS.H      Data structure definitions and equates

System/Device Dependent:

    MSXxxx.ASM      System-dependent code for system xxx
    MSYxxx.ASM      System-dependent screen and keyboard code
    MSZxxx.ASM      Modem control (modem-dependent)

The  modular  organization  allows  easier  modification of the program,
quicker transfer  of  modified    portions  from    system-to-system.    The
modules  are  designed    to be well-defined and self-contained, such that
they can be easily replaced.  For instance, someone who prefers  windows
and  mice  to  typing  commands could replace the command parsing module
without having to worry about the effect on the other modules.

To assemble any of the kermit modules, file  MSDEFS.H  must  be  on  the
default disk.
                                      111


All  the  Kermit  implementations  require  the  modules  MSCMD, MSCOMM,
MSFILE, MSKERM, MSRECV, MSSEND, MSSERV, MSSET, MSTERM.

The IBM PC version requires MSXIBM and MSYIBM as well.

The Rainbow version requires MSXRB and MSXDMB; MSXDMB must be the  first
object    file  given  to  the  linker for Kermit to link properly for the
Rainbow.

The HP150 version requires MSXHP150, the Wang version  requires  MSXWNG,
and the generic version requires MSXGEN.

Once  all the required object modules exist, they may be linked together
to produce Kermit.  For example, on the Rainbow:

  A>link

     Microsoft Object Linker V2.00
  (C) Copyright 1982 by Microsoft Inc.

  Object Modules [.OBJ]: msxdmb mskerm msxrb mscomm msset mssend +
  msrecv msserv msfile msterm mscmd
  Run File [MSXDMB.EXE]: kermit
  List File [NUL.MAP]: kermit

  A>


9.9. Adding Support For New Systems

You can bring Kermit-MS to systems that are not explicitly supported  in
one  of two ways -- attempt to run the "generic" MS-DOS Kermit on it, or
add explicit code to support your system.


9.9.1. Generic MS-DOS Kermit

To get started with Kermit on a new system, try running "generic" MS-DOS
Kermit; in many cases, it will run as  is.    The  generic  version  ac-
complishes  all  its  port and console i/o through DOS calls, and during
terminal connection does not attempt to emulate any particular    kind  of
terminal.    In  some  cases, the generic version may still require some
fiddling to run on a new system; for instance, different  systems  refer
to  their  communication  ports in different ways -- COM1, AUX, etc.  It
attempts to do this automatically by trying various DOS file handles for
the communication port, and asking you to supply  one  if  it  does  not
succeed.

Generic MS-DOS Kermit will probably run no faster than 1200 baud, and it
only works with DOS 2.0 or later.
                                      112


9.9.2. Adding System-Dependent Code

The following is a guide to the system dependent module of Kermit-MS.


       SPECIFICATION FOR KERMIT SYSTEM-DEPENDENT MODULES

          by Jeff Damens, Columbia University

All  the system-independent global data structures used in Kermit-MS are
defined in the file MSDEFS.H.

The routine MSXxxx.ASM contains system-dependent support for system xxx,
except for terminal emulation, which is in MSXxxx.ASM, described below.

The routines in the MSX module may change any registers  but  the  stack
pointer  and  segment registers, unless otherwise noted.  A routine that
returns via a RET instruction is said to return normally; a routine that
skip returns is one that returns to three bytes past the  normal  return
address.

Global variables that must be defined in the system-dependent module:

XOFSNT        byte.    This should be set to a non-zero value if we are
        doing flow control and have sent an  XOFF  character  to
        the remote host, zero otherwise.

MACHNAM     byte.     A  $-terminated  string identifying the machine
        this version of Kermit is for; it is printed when Kermit
        starts up.

SETKTAB     byte.  A keyword table associating terminal key names to
        16-bit scan code values, used in the  set  key    command.
        If  the  kermit  version  can  accept  arbitrary decimal
        values as scan codes, the word "SCAN" should  appear  in
        the  table with a scan value of -1.  If key redefinition
        is not implemented, the first byte of the  table  should
        be a zero.

SETKHLP     byte.     A  $-terminated  string to be printed when ? is
        typed in the SET KEY command.  This is usually simply  a
        list  of  the  key  names  in  SETKTAB.  SETKHLP must be
        defined even if key redefinition is not implemented,  to
        satisfy  the  linker;  if key redefinition is not imple-
        mented, SETKHLP will never be displayed.

COUNT        word.  The number of  characters  in  the  serial  input
        buffer,  if  known.  This is how Kermit knows to send an
        XON if the serial handler has sent an XOFF.  If the num-
        ber of characters  in  the  buffer  isn't  known,  COUNT
        should be 0.

These  are  the required entry points for the system dependent dependent
module MSXxxx.ASM.
                                      113


SERINI

Parameters    None.

Returns     Normally, no return value.

Description    Perform  any initialization that must be done before the
        serial port can be used, including  setting  baud  rate,
        interrupt  vectors, etc.  Parity and baud rate should be
        set according to the values in the  PORTINFO  structure.
        The  external  variable  PORTVAL  points to the PORTINFO
        structure for the current port.    Calling  SERINI  more
        than  once  without an intervening call to SERRST should
        have no effect.


SERRST

Parameters    None.

Returns     Normally, no return value.

Description    Undoes any  initialization  done  by  SERINI,  including
        resetting  the serial port, restoring any interrupt vec-
        tors changed by SERINI, etc.   Calling    this  more  than
        once  without  an  intervening    call to SERINI should be
        harmless.


CLRBUF

Parameters    None.

Returns     Normally, no return value.

Description    Remove and discard from the serial port's  input  buffer
        any characters sent by the remote host that have not yet
        been  read  by Kermit, and set COUNT to 0.  This is used
        before a file transfer to flush NAK's that accumulate in
        the buffer when the remote host is in server mode.
                                      114


OUTCHR

Parameters    A character in AH.

Returns     Skip  returns  if  the    character  has been transmitted;
        returns normally if the character can not be transmitted
        because of a hardware error.

Description    Sends the character in AH  out    the  currently    selected
        serial    port.     OUTCHR can assume that SERINI will have
        been called previously. OUTCHR should call the    external
        routine  DOPAR to set the parity of the character if the
        communications    hardware   doesn't   automatically   set
        parity.    Flow  control should be honored; the external
        variable PORTVAL contains a pointer to a PORTINFO struc-
        ture (as defined in  MSDEFS.H)    containing  the  current
        flow control definitions.


COMS

Parameters    None.

Returns     Normally  if  a parse error is encountered, skip returns
        otherwise.

Description    Called by the SET PORT command.  On a machine with  mul-
        tiple  serial  ports,  COMS should parse for the name or
        number of a serial port and make that the port    used  by
        succeeding  calls to SERINI, PRTCHR, OUTCHR, and SERRST.
        It should set the external variable PORTVAL to point  to
        one  of the external port structures PORT1 or PORT2, and
        set COMFLG in the FLAGS structure to 1 for port  one,  0
        for  port  2.     For  implementations  that use only one
        serial port, COMS should print a message to that  effect
        and skip return.


VTS

Parameters    None.

Returns     Normally  if  a parse error is encountered, skip returns
        otherwise.

Description    Parses for an ON or OFF, sets HEATH-19    emulation  while
        in terminal emulation appropriately.  The VTFLG field of
        the  FLAGS  structure should be set non-zero if HEATH-29
        emulation is on, zero otherwise.  If HEATH-19  emulation
        is not done, VTS should print a message and skip return.
                                      115


DODEL

Parameters    None.

Returns     Normally, no return value.

Description    Erases the character immediately to the left of the cur-
        sor from the screen, then backs up the cursor.


CTLU

Parameters    None.

Returns     Normally, no return value.

Description    Move the cursor to the left margin, then clear the line.


CMBLNK

Parameters    None.

Returns     Normally, no return value.

Description    Clears the screen and homes the cursor.


LOCATE

Parameters    None.

Returns     Normally, no return value.

Description    Homes the cursor.


LCLINI

Parameters    None.

Returns     Normally, no return value.

Description    Performs any system-dependent initialization required by
        this implementation.
                                      116


PRTCHR

Parameters    None.

Returns     Normally,  with  the  next  character from the currently
        selected serial port in AL.  Skip returns if no  charac-
        ter is available.

Description    Reads  the  next character from the current serial port.
        PRTCHR can assume SERINI has been called previously, and
        should handle flow control correctly.


DOBAUD

Parameters    None.

Returns     Normally, no return value.

Description    Sets the baud rate for the current port.  The baud  rate
        should    be  obtained from the BAUD field of the PORTINFO
        structure, pointed to by the external variable PORTVAL.


CLEARL

Parameters    None.

Returns     Normally, no return value.

Description    Clears from the cursor to the end of the current line.


DODISK

Parameters    None.

Returns     Normally, no return value.

Description    Sets the external variable DRIVES to the number of  disk
        drives attached to the machine.


GETBAUD

Parameters    None.

Returns     Normally, no return value.

Description    Store  current    baud rate of the currently selected port
        in the BAUD field of  the  current  PORTINFO  structure,
        which  is pointed to by PORTVAL.  If the baud rate is to
        default to a particular value, this  routine  can  store
        that value into the BAUD field instead.
                                      117


BEEP

Parameters    None.

Returns     Normally, no return value.

Description    Rings the terminal bell.


PUTHLP

Parameters    A pointer to a string in AX.

Returns     Normally, no return value.

Description    Writes    the  null-terminated  string  given in AX to the
        terminal.  This is used to display help and status  mes-
        sages.    The IBM and Rainbow versions write the string in
        a reverse video box.


PUTMOD

Parameters    A pointer to a string in AX.

Returns     Normally, no return value.

Description    Writes    the  null-terminated  string  given in AX to the
        last line of the screen, in inverse video if possible.


CLRMOD

Parameters    None.

Returns     Normally, no return value.

Description    Clears the line written by PUTMOD.


POSCUR

Parameters    Row in DH, column in DL.

Returns     Normally, no return value.

Description    Positions the cursor to the row and column given in  DX.
        Rows and columns both originate at 0 (not 1!).
                                      118


SENDBR

Parameters    None.

Returns     Normally, no return value.

Description    Send a break to the current serial port.


SHOWKEY

Parameters    Pointer  to  a    terminal  argument block in AX (see TERM
        below).

Returns     Normally, with a string pointer in AX and the length  of
        the string in CX.

Description    Called    by  the  SHOW KEY command.  Reads a key from the
        terminal    and    returns    a    string     containing
        implementation-dependent  information  about the key. In
        the  usual  case,  the     string   contains   the   key's
        (machine-dependent)  scan code, and the key's definition
        (if any) from the terminal argument block.   The  length
        of  the  returned  string should be returned in CX.  The
        string may contain any characters;  unprintable  charac-
        ters  will be quoted when the string is printed.  If the
        implementation does not support key redefinition,  SHOW-
        KEY may return a static string saying so.


TERM

Parameters    Pointer to terminal argument block in AX.

Returns     Normally, no return value.

Description    Do terminal emulation, based on argument block described
        below...




The  terminal emulator is supplied in the file MSYxxx.ASM.  The terminal
argument block passed to the terminal emulator has the following fields:

FLGS        Byte containing flags.    Flags are:

        SCRSAM (80H)    If on, the terminal  emulator  shouldn't
                re-display the screen when entered.

        CAPT (40H)    Capture  output.    If    on,  the routine
                passed in field  CAPTR    is  called  with
                each character sent to the screen.

        EMHEATH (20H)    Emulate a Heath-19 terminal if on.
                                      119


        HAVTT (10H)    A key redefinition table is present.

        TRNCTL (08H)    Print  control character X as ^X (useful
                for debugging).

        MODOFF (04H)    Do not display emulator mode line if on.

        LCLECHO (01H)    Echo keyboard characters on  the  screen
                in addition to sending them to the port.

PRT        Port  to  use  for terminal emulation, used only in mode
        line.  This is just a copy of COMFLG in FLAGS.

COLS        Number of columns on screen.

ROWS        Number of rows on screen.

CAPTR        Routine to call to  with  each    character  sent  to  the
        screen if CAPT flag is on.  Characters are passed in AL.

BELLD        Bell divisor (used only on IBM).

KLEN        Number    of keys in key redefinition table, if HAVTT flag
        is on.

KTAB        Address of key redefinition table.  The key redefinition
        table is a table  of  KLEN  16-bit  scan  codes.    Each
        (machine  dependent)  scan code represents a key that is
        redefined.

KRPL        Address of key replacement table.  The    key  replacement
        table  parallels  the  key  redefinition  table given in
        KTAB.  Entries    in  the  replacement  table  are  16-bit
        pointers  to  redefinitions.    Each  redefinition has a
        one-byte length, followed by the definition.

ESCC        Escape character (single byte).  When this character  is
        typed to the emulator, it should return.

BAUDB        byte.     Bits  describing  the    baud  rate  so it can be
        printed on the mode line.  This is a copy  of  the  BAUD
        field in the PORTINFO structure.  Currently used only on
        the IBM.  See MSDEFS.H for possible values.

PARITY        byte.     Current parity to print on the mode line.  This
        is a copy of PARFLG in the  PORTINFO  structure.    Cur-
        rently    used only on the IBM.  See MSDEFS.H for possible
        values.
                                      120


9.10. Heath/Zenith-19 Control Codes

The  Heath/Zenith-19  terminal is equivalent to the DEC VT52 with exten-
sions for line and character insertion and deletion.  Items marked  with
an asterisk are not currently supported by Kermit-MS H19 emulation.


Cursor Functions

  Sequence    Mnemonic      Definition
   ESC H      HCUH      Cursor Home
   ESC C      HCUF      Cursor Forward
   ESC D      HCUB      Cursor Backward
   ESC B      HCUD      Cursor Down
   ESC A      HCUU      Cursor Up
   ESC I      HRI      Reverse Index
  *ESC n      HCPR      Cursor Position Report
  *ESC j      HSCP      Save Cursor Position
  *ESC k      HRCP      Set Cursor to Previously Saved Position
   ESC Y      HDCA      Direct Cursor Addressing, 1-based:
              31+line# 31+col# (same as VT52)



Erasing and Editing

  Sequence    Mnemonic      Definition
   ESC E      HCD      Clear Display (Shift Erase)
   ESC b      HBD      Erase Beginning of Display
   ESC J      HEOP      Erase to End of Page (Erase Key)
   ESC l      HEL      Erase Entire Line
   ESC o      HEBL      Erase Beginning of Line
   ESC K      HEOL      Erase to End of Line
   ESC L      HIL      Insert Line
   ESC M      HDL      Delete Line
   ESC N      HDCH      Delete Character
   ESC @      HEIM      Enter Insert Character Mode
   ESC O      HERM      Exit Insert Character Mode



Configuration

  Sequence    Mnemonic      Definition
  *ESC z      HRAM      Reset to Power-Up Configuration
  *ESC r Bn   HMBR      Modify Baud Rate: Bn=
                A=110,  B=150,  C=300, D=600,  E=1200,
                F=1800, G=2000, H=2400, I=3600, J=4800,
                K=7200, L=9600, M=19200

  *ESC x Ps   HSM      Set Mode(s): Ps=
                1 = Enable 25th line
                2 = No key click
                3 = Hold screen mode
                4 = Block cursor
                5 = Cursor off
                                      121


                6 = Keypad shifted
                7 = Alternate keypad mode
                8 = Auto line feed on CR
                9 = Auto CR on line feed

  *ESC y Ps   HRM      Reset mode(s): Ps=
                1 = Disable 25th line
                2 = Enable key click
                3 = Exit hold screen mode
                4 = Underscore cursor
                5 = Cursor on
                6 = Keypad unshifted
                7 = Exit alternate keypad mode
                8 = No auto line feed
                9 = No auto CR

  *ESC <      HEAM      Enter ANSI Mode



Modes of Operation

  Sequence    Mnemonic      Definition
  *ESC [      HEHS      Enter Hold Screen Mode
  *ESC \      HXHS      Exit Hold Screen Mode
   ESC p      HERV      Enter Reverse Video Mode
   ESC q      HXRV      Exit Reverse Video Mode
  *ESC F      HEGM      Enter Graphics Mode
  *ESC G      HXGM      Exit Graphics Mode
  *ESC t      HEKS      Enter Keypad Shifted Mode
  *ESC u      HXKS      Exit Keypad Shifted Mode
  *ESC =      HAKM      Enter Alternare Keypad Mode
  *ESC >      HXAM      Exit Alternate Keypad Mode



  Additional Operations

  Sequence    Mnemonic      Definition
  *ESC }      HDK      Keyboard Disable
  *ESC {      HEK      Keyboard Enable
   ESC v      HEWA      Wrap Around at End of Line
   ESC w      HXWA      Discard at End of Line
   ESC Z      HID      Identify as VT52 (ESC / K)
  *ESC ]      HX25      Transmit 25th Line
  *ESC #      HXMP      Transmit Page

  The  Heath-19  transmits  the  following  sequences,    but  it will not
  respond to them if they are received.  Kermit-MS  will  transmit  them
  only if they are programmed with SET KEY.

   ESC S      HF1      Function Key #1
   ESC T      HF2      Function Key #2
   ESC U      HF3      Function Key #3
   ESC V      HF4      Function Key #4
   ESC W      HF5      Function Key #5
                                      122


   ESC P      HF7      Function Key #7
   ESC Q      HF8      Function Key #8
   ESC R      HF9      Function Key #9
                                      123


Index

                        RECEIVE   86
      ANSI.SYS   94             Recognition   83
      Autodialer   100
                        Smart Modem   100
      Batch Operation of Kermit-MS     84
      Baud Rate   92            Telenet   95
      Beeper   92                Timeout   98
      Bell     92
      Binary Files     96            Warning   98
                        Wildcard   81
      Cancelling a File Transfer   86, 87
      Command Files   98
      Command Macro   99
      CONNECT   100
      Control-X   86, 87
      Control-Z   86, 87

      Debugging   93
      DEFINE   99
      DO Command   99

      Eighth-Bit Prefix   96
      EMACS   102
      End Of File    82, 93
      EOF    93
      Escape Character for CONNECT     94

      File Renaming   98
      File Warning     98
      Flow Control     94

      Generic MS-DOS Kermit   111

      Handshake   94
      Heath-19 Terminal Emulation    94, 100,
          120
      Help     83

      IBM PC   79
      Incomplete File Disposition    87

      Key Redefinition   95

      Local Echoing   95

      Macro   99
      META Key   102
      Mode Line   100
      Modem   100
      MS-DOS   79

      Parity   95
      PC-DOS   79
                                    i


               Table of Contents

9. MS-DOS KERMIT                              79

9.1. The MS-DOS File System                          80
     9.1.1. File Specifications                       80
     9.1.2. File Formats                          81
9.2. Program Operation                              82
9.3. Kermit-MS Commands                           84
     9.3.1. Commands for File Transfer                      85
     9.3.2. Commands for Connecting and Disconnecting              88
     9.3.3. Commands for File Management                  89
     9.3.4. The SERVER Command                          91
     9.3.5. The SET Command                          92
     9.3.6. The SHOW Command                          98
     9.3.7. Command Macros                          99
9.4. Terminal Emulation                          100
9.5. Installation of Kermit-MS                         103
     9.5.1. Try Again To Find A Kermit Disk                 103
     9.5.2. Bootstrapping From the Communication Line             103
      9.5.2.1. Use An Existing File Capture Facility         104
      9.5.2.2. Type In Your Own Bootstrap                 104
9.6. Compatibility with Older Versions of MS-DOS Kermit          109
9.7. What's Missing                                                  109
9.8. Program Organization                         110
9.9. Adding Support For New Systems                     111
     9.9.1. Generic MS-DOS Kermit                     111
     9.9.2. Adding System-Dependent Code                 112
9.10. Heath/Zenith-19 Control Codes                     120

Index                                     123