Columbia Kermit/kermit.zip/hp9826/hp9kerdoc.txt

Text File | 2020-01-01 | 13KB | 374 lines

                    HP9826/9836  HP Pascal Kermit

                  Mike Gallaher, Rutgers University

                           December 1984

WARNING: This document isn't finished yet!  Don't be surprised if you
can't find a section cited elsewhere in the document...


This Kermit is intended to run on the HP9826/9836 workstations under
the HP Pascal Language System.  It depends on various HP Pascal
language extensions, such as modules and string data types.  The
current implementation is minimal - it will only transfer text files,
only one file at a time.  It can talk to a server, but it is not smart
(i.e., no timeouts).  The user interface is display oriented; for
example, this Kermit maintains a continuous status display during file
transfers.  I plan to be adding a lot to this implementation quite
soon, to improve the user command interface, error handling, add login
packets, and maybe binary transfers.

This file tells the following -

    - the history of this implementation
    - what (mis)features this Kermit has
    - plans for future development
    - how to get the Kermit sources onto your HP machine
    - how to compile and link HP Kermit
    - how to use this Kermit
    - program structure and internals

This implementation is maintained by

US mail:            Mike Gallaher
                Rutgers University
                Box 879
                Piscataway, NJ 08876

Arpanet
  (preferred to US mail):    [e-mail]



History
-------

This implementation of Kermit for the HP9826/9836 workstations is
based on the RT-11 OMSI Pascal Kermit that was developed by Philip
Murton, University of Toronto Computing Services, and Michael K.
Weisberg, Mount Sinai Hospital.

The protocol support routines are taken mostly intact from the RT-11
version.  The main modifications are in the program structure - it has
been split into modules - in the IO mechanisms, and in the user
interface.



Features of this Kermit
-----------------------

This implementation is, at the moment, a minimally functional but
working Kermit.  A lot of extensions are planned, however.  The
important features (marked by +) and misfeatures (marked by -)
of the current version are

    - errors not handled gracefully
    - only transfers one file at a time
    - does not handle wild cards
    - only transfers text files
    + continuous status display during file transfers
    + can talk to a server
    - does not handle timeouts
    - only acts as local Kermit
    + reasonably friendly command interface, loosely modeled
      after the TOPS-20 COMND facility.

The user interface is based on a primitive window display facility.
There is a window for the status display, one for command echoing, one
for error messages, and one for help messages.  The command input
interface is loosely based on the TOPS-20 COMND parsing facility,
which features keyword recognition, keyword and filename completion,
and dynamically available help messages and guide words.  The Kermit
command interface is much more modest - it allows keyword
abbreviation, but at the moment that's about all.  Soon to be added
are dynamic help messages and keyword completion.


Future development
------------------

The following extensions are planned, in my own order of priority:

    o Fix the error handling mechanism, which is the most serious
      deficiency.

    o Add the ability to send login packets, to work, for example,
      in conjunction with a server on a mainframe for file access
      checking.

    o Implement multiple file transfers via single command.

    o Fix the command interface so it really works and add help
      messages.

    o Implement wild card file transmission.

    o Implement binary file transfers.

    o Add timeout capability.


How to get the HP Kermit sources onto your HP machine
-----------------------------------------------------

This section tells how to get the Kermit sources onto your HP system,
where they will be compiled and linked (described in the next
section).  I'll outline the procedure first, then describe it in
detail.

First, you need to get the source files from the Kermit distribution
tape, or via network from the Kermit repository at Columbia.  You will
load these files onto some convenient system, which I will hereafter
call the host.  Any system that can run Kermit, and onto which you can
somehow get the HP-Kermit source files, will do as a host.  You must
rename the files (see below) and then use a primitive downloading
program to download a baby Kermit to the HP system.  Then you use the
baby Kermit to download the full-fledged Kermit source files.

The HP Kermit source files, like those of a few other implementations,
have different names on the distribution tape than they must have on
the system on which they will be compiled and run.  This is done to
make the names agreeable to as many systems as possible (e.g., making
the name less than 9 characters so a VAX/VMS system will like it).
Once the files are on whatever host system you are using (having been
FTPed or copied from the distribution tape), you must rename them
according to the table below before moving them to the target HP
system.  This is VERY important, because if you don't at least change
the extension to .TEXT, the HP file system will store them in the
wrong format, and the editor, compiler, etc. will refuse to have
anything to do with them.

Kermit Distrution Name    HP Pascal System Name   Description

 HP9KER.PAS                KRMCMD.TEXT            Command Parser
 HP9KER.PAS                KRMGUTS.TEXT           Protocol Module
 HP9KER.PAS                KRMIO.TEXT             I/O Module
 HP9KER.DOC                KRMDOC.TEXT            Documentation
 HP9KER.PAS                KRMMAIN.TEXT           Main Program Modules
 HP9KER.PAS                KRMRPT.TEXT            Error Reporting Modules
 HP9KER.PAS                KRMWNDW.TEXT           Window Management Modules
 (reproduced below)        KRMCOMP.TEXT           Compilation Procedure
 (reproduced below)        KRMLINK.TEXT           Linking Procedure

Compiling and Linking this Kermit
---------------------------------

The program source resides in six files, each of which contains one or
more modules (these are more fully documented in the section on
program structure):

  KRMMAIN.TEXT        The main program
  KRMCMD.TEXT        Generalized input parsing package, loosely
             based on TOPS-20 COMND facility.
  KRMGUTS.TEXT        Kermit protocol support routines
  KRMIO.TEXT        Byte-oriented string manipulation and IO
             facilities, terminal emulation package
  KRMRPT.TEXT        Error and status reporting routines
  KRMWINDOW.TEXT    Generalized, rudimentary window display
             manager package

Each of these files must be compiled, in the order dictated by which
modules depend on which other modules, and then linked together to
form the executable KERMIT.CODE file.  There are two command stream
files provided to do this:

    KRMCOMP.TEXT    Compiles all the modules in the right order,
             and then invokes KRMLINK.TEXT to build the
             .CODE file.  Here it is:
CKRMWNDW
N
CKRMRPT
N
CKRMCMD
N
CKRMIO
N
CKRMGUTS
N
CKRMMAIN
N
SKRMLINK


    KRMLINK.TEXT    Links the modules together into KERMIT.CODE.
            Here it is:

LOKERMIT
IKRMWNDW
AIKRMRPT
AIKRMCMD
AIKRMIO
AIKRMGUTS
AIKRMMAIN
ALKQXKERMIT


All the source files and stream files are expected to be found in the
current default directory.  If they are, then invoking the file
KRMCOMP.TEXT (using the S command at the top level) will compile and
link all the modules, producing a ready-to-run KERMIT.CODE in the
default directory.

If you have modified one of the modules, but haven't changed the
interface text, you need only compile that module alone, then invoke
KRMLINK.TEXT.  If you have modified the interface text, say, by adding
a new exported routine, then you may have to recompile any modules
that depend on objects exported from that module.


How to use this Kermit
----------------------

When Kermit is started, it clears the screen and prints the command
prompt

HP-Kermit>

and waits for you to enter a command.

The valid commands are:

    EXIT        Return to top level
    RECEIVE        Request the remote server to send a given file
    SEND        Send a given file to the remote server
    SET        Set flags and operating parameters
    SHOW        Show current flag and parameter settings
    TN        Open a terminal connection to the remote host

The command interface is modeled after the TOPS-20 COMND facility.
User input is echoed in the command window as it is typed.  Typing
Backspace (BS) or Delete (CLR LN on the HP) will cause the last typed
character, if any, to be deleted.  CTRL-U will cause the entire line
to be aborted.

At present, Kermit only parses one token at a time - if you type "SEND ",
Kermit has already parsed the SEND keyword, and is now expecting a
filename; you can't BS past the space.  This is an annoyance that will
go away in future releases...  For now, the only way you can change
your mind at this point is to type CTRL-U to abort the entire line,
and start over.

Typing a question mark ("?") will generally tell you, via a message in
the help window, what Kermit is expecting you to type at that point.
For example, if you type a "?" immediately after the HP-Kermit>
prompt, Kermit will print a list of the valid commands in the help
window.

Keywords, such as commands and parameter names, can be abbreviated to
as few characters as makes the keyword unambiguous.
If you type "rec ?" Kermit will recognize the abbreviation for the
RECEIVE command, and then print "Input filespec" in the help window in
response to the "?".

Program structure and internals
-------------------------------



System dependencies
-------------------

Since this implementation is intended to run only on HP equipment, in
particular the 9836 workstation, it takes advantage of the HP Pascal
language extensions and operating system features, even where this
might make it non-transportable.  The program uses the following
non-standard features:

    modules - The program consists of several modules, which
        reside in several different files.

    string data types - used extensively in all modules.

    try-recover error trapping mechanism

parameters are stored in the file as a string of characters as would
be sent in an initialization packet.  This didn't turn out to be very
useful though, as I instead set the defaults using the relevant CONSTs
DEFxxxxx rather than try to figure out how to encode the parameters by
hand.  The parameters in KERMIT.PRM will override the CONSTs if it
exists.  If KERMIT.PRM does not exist, the program will just ignore
it.  (To see if KERMIT.PRM exists, the parameter setting code calls
the Exists procedure (in KRMIO.TEXT), which sets a trap on file open
errors, tries to open the file, notices whether the trap was taken,
and resets the file error trap.)

Program structure:

This implementation of KERMIT is composed of seven modules:

    main program    is the top level program
    KRMCMD    provides a user command interface modeled after, but
        not nearly as comprehensive as, the TOPS-20 COMND
        facility.
    KRMGUTS    contains the routines and data structures that
        actually implement the KERMIT protocol.
    ERR_CODES  defines the error codes used to identify error and
        status conditions
    KRMRPT    provides a uniform error reporting and status display
        facility
    KRMIO    supports the special eight-bit file and serial port
        I/O facilities needed by KRMGUTS
    WINDOWLIB    provides a rudimentary text window facility,
        wherein the screen is partitioned into a number
        of rectangular regions (windows), in which text may be
        displayed.


The modules reside in six files, as follows:

    File        Modules
    --------    ------------
    KRMMAIN        main program
    KRMGUTS        KRMGUTS
    KRMCMD        KRMCMD
    KRMIO        KRMIO
    KRMWNDW        WINDOWLIB
    KRMRPT        ERR_CODES
            KRMRPT


The heirarchical relation among the modules is as follows:

               KRMMAIN
        KRMCMD            KRMGUTS
                    KRMIO
        KRMRPT/ERR_CODES
        KRMWNDW

The modules in the left column comprise the user interface, whereas
the modules in the right column implement the Kermit protocol.  The
modules KRMRPT and ERR_CODES, which provide the error and status
reporting mechanism, are used by all modules above them.  The
functions performed by each of the modules is described below.



KRMGUTS is the module that does all the work - it actually implements
the Kermit protocol.  The other modules just interface it to the
operating system's file and serial port I/O, and provide a way for the
user to type commands to KRMGUTS.

-----

Date: 20 Nov 85 21:59:33 EST
From: Mike Gallaher <[e-mail]>
Subject: HP98xx kermit support

Please remove my name from the list as the support contact for HP98xx
kermit.  There are no 98xx's where I now work...  I had forgotten I was
still on the list until I found a couple of queries in my mailbox!

The only machine that the HP98xx kermit was actually run on here was
the 9836.  HP Pascal is supposed to be, and seems to be, portable across
at least the 98xx line.  The only questions that people asked me seemed
to arise from library functions moving around in the newer HP releases,
which were solved by looking in their documentation and using the
librarian to hunt them down.  Sorry I can't provide more details than that...

thanks,
Mike Gallaher

-------