Columbia Kermit/kermit.zip/mumps/mpkerdoc.txt

Text File | 2020-01-01 | 19KB | 392 lines

MUMPS Kermit

Kermit-M is written in the 1982 ANSI Standard MUMPS language.  MUMPS is
typically used for transaction-oriented data base applications.  There are two
types of MUMPS implementations, those running under some host operating system
(e.g. CP/M, VMS, Unix), and those with their own integrated operating system.
In the former type, it is probably faster to use a Kermit developed for the
host operating system, and then use local utility programs to transfer between
the host operating system and MUMPS data structures.  Kermit-M was developed
on M/11, which has its own integrated operating system.  In this case, Kermit
must be written in the MUMPS language (since that's the only language
available on such systems), and Kermit must be able to understand MUMPS data
structures.  Since MUMPS was never intended to be a systems programming
language, there are certain performance penalties in using Kermit-M.

Kermit-M is divided into two main sections.  The first provides most of the
functions of other Kermits, including Server mode.  There is no 8-bit quoting,
so that only the 7-bit ASCII character set is supported.  In this section, he
command parser follows TOPS-20 style, with extensive HELP.  The second
provides the interface between the Kermit file structure and MUMPS data
structures.  This is accessed with the MUMPS command, and is organized as a
series of menus, in the more usual MUMPS interactive style.  Since MUMPS
systems do not have typical (e.g. TOPS-20 style) file systems, Kermit-M must
simulate a file system within MUMPS data structures, and the MUMPS command
must provide typical file system services (Directory of files; Copy, Rename,
and Erase files).  The MUMPS command also provides the mechanism for
interpreting Kermit files as MUMPS data structures, and vice-versa.  The MUMPS
data structures that are supported are 1) routines, 2) globals, 3) sequential
'files' (e.g. magtape, sequential disk processor, terminals), and 4) globals
interpreted as sequential files.

Although MUMPS is an ANSI standard language, certain sections of the language
which are critical to Kermit-M are implementation-specific.  Almost everything
dealing with I/O is in this category.  The initial version of Kermit-M was
developed at the New York State College of Veterinary Medicine, on a PDP-11/44
running InterSystems' M/11, Version 5.  It will have to be modifed for any
other MUMPS implementation.  A separate document has been prepared for those
who need to prepare a new version.

Installation of Kermit-M

Kermit-M consists of about 20 MUMPS routines (all starting with the prefix
ZKR) which are about 2 to 4 KB of text), and one reference global (^ZKRX)
which is about 40KB.

The routines, reference file, and external comments are provided in two ways:
as 3 files on 800BPI 9 track magnetic tape (separated by tape marks) , and as
TOPS-20 files named, respectively, 'KERMITM.ROU', 'KERMITM.GLO', and
'KERMITM.ECM'.  [Editors note:  These have been renamed to MPKERMIT.ROU,
MPKERMIT.GLO, and .ECM, respectively, for distribution purposes.]

The first file contains the text of all routines.  The first line is a string
of MUMPS code that allows the rest of the file to be loaded according to the
proposed MDC standard on interchange of routines.  (This code is 'R DATE F
I=0:0 R ROU Q:ROU=""  ZL  ZS @ROU'.) The second line is the date and time the
file was written.  Following these two header lines are the routine texts.
Each routine begins with one line containing just its name, and ends with a
null line.  The file ends with an additional null line.  If the file can be
opened as a sequential device, all the routines can be loaded into the MUMPS
routine space by entering the following MUMPS code: 'R X X X'.

The second file contains the reference file, ^ZKRX.  The first line is a
string of MUMPS code that allows the rest of the file to be loaded according
to the proposed MDC standard on interchange of globals.  (This code is 'R DATE
F I=0:0 R GREF Q:GREF=""  R DATA S @GREF=DATA'.).  The second line is the date
and time the file was written.  Follwing this are pairs of lines, the first of
each pair being the global reference, and the second being the data to be
stored at that reference.  The file ends with a null line in place of a global
reference.  If the file can be opened as a sequential device, the global can
be loaded into the MUMPS data space by entering the following MUMPS code: 'R X
X X'.

The third file contains 'external' comments.  These are additional comments,
too lengthy to fit in the routine text, which are stored in global ^COMMENT.
The first two subscripts in ^COMMENT are the routine name and the label to
which the comment applies.  The third subscript is always '0', and the fourth
level contains text lines, at subscripts 1 by 1.  This file is organized and
loaded exactly as the second file (reference global).

Once the routines and reference global are loaded, it may be necessary to make
certain system-dependent changes.  See the document 'Adapting Kermit-M to
different implementations of MUMPS'.  On InterSystems M/11 Version 5 systems,
either a) Kermit-M must be loaded into the 'manager' UCI, or b) routine ZKRTC
must be moved to the 'manager' UCI and renamed to %ZKRTC, and the two calls to
this routine (TTYON+1^ZKR and ZKRC+5^ZKRC) must be edited accordingly.


               New York State College of Veterinary Medicine
                        Veterinary Computing Facility
                            Kermit-M User's Guide

Introduction

Kermit is a program that transfers information between different computer
systems.  The original Kermit was written for the TOPS20 operating system.
Since then, Kermits have been developed for Unix, VMS, CMS, RT-11, CP/M,
MS-DOS, and Apple DOS.  These operating systems run on a wide variety of
computers, from micros (Apple II, DEC Rainbow, IBM PC) thru minis (PDP-11,
VAX-11) to mainframes (IBM 370, DECSYSTEM-20).  Kermit-M is a version of
Kermit that is written in MUMPS.  The original version is designed for PDP-11
computers running InterSystem's M/11 operating system (version 5).

All Kermits communicate with each other.  Thus with the development of
Kermit-M, it is now possible to transfer routines, globals, and sequential
files between our M/11 systems and many other computer systems.  For example,
you could develop programs in standard MUMPS on an M/11 system, and then
download them to a micro-MUMPS system.  Or, you could create data files from
searches on M/11, and transfer them to a mainframe system or VMS) for
statistical analysis.

Limitations

Kermit can achieve a thruput of about 50 characters per second, which is about
6.5 hours per megabyte; in 20 minutes Kermit could transfer about 50 disk
blocks.  Clearly, this speed is only acceptable for transferring MUMPS
routines or small data files.

Over a 9600 bps direct connection, Kermit is about 3 times as fast as over a
1200 bps phone line, i.e. about 150 cps.  This speed is still not acceptable
for large data files.

Industry-standard magnetic tape (9 track, 1/2 inch) is the best method of
transferring large quantities of data between systems.

System load due to Kermit-M

Kermit-M on the NYSCVM MUMPS system is a fairly intensive user of both the
processor and the disk or during file transfer to or from other systems, or
while Kermit-M files are being transferred to or from MUMPS data structures.
Programmers should avoid using Kermit-M during times of heavy system use.

Using Kermit-M -- an overview

To SEND files to another computer, the basic steps are:

     1. transfer from MUMPS data structures (e.g. routines) to the
        Kermit-M file system (see below).

     2. connect to the other computer

     3. Issue the SEND command at the Kermit-M end, and the RECEIVE
        command at the other end

     4. break the connection (may involve logging off the other system)

To RECEIVE files from another computer:

     1. connect to the other computer

     2. Issue the RECEIVE command at the Kermit-M end, and the SEND
        command at the other end

     3. break the connection

     4. transfer from the Kermit-M file system to MUMPS data structures.

Some detailed examples of sessions are given at the end of this document.

The Kermit-M file system

The file system is a familiar concept to microcomputer and traditional
time-sharing system users, but not to most MUMPS programmers.  Basically, the
data accessible to the program is a set of sequential (line-by-line) files.
These may represent globals, routines, or MUMPS sequential files, but they are
all stored as a list of lines, separated by <CR><LF>.  Each file has a unique
name, which is separated into two parts:

     filename.filetype

     for example, ZKR.ROU

The filename names the information, and the filetype gives some indication of
what kind of data is in the file.  Common filetypes are:

     .ROU  -- a set of MUMPS routines, in %RO/%RI format
     .MMP  -- one micro-MUMPS routine
     .GLO  -- global references and data, in %GO/%GI format
     .TXT  -- text

The filename usually represents the MUMPS data structure in some way.  For
example, file ZKR.ROU might be a set of routines from program ZKR, and file
ZKRX.GLO might be ^ZKRX.

There are file system commands for managing files: ERASE to delete unwanted
files, COPY to make another copy of a file, RENAME to change a file name, and
DIRECTORY to see what files are in the file system.  As you work in the file
system, you are often asked to specify a file or set of files.  You may enter
an exact file name, or you can use 'wild cards' in either or both of the
filename and filetype.  The 'wild card' is an asterisk (*) character, which
indicates that any (or no) completion of the field is acceptable.  For
example,

     Z*.ROU    would include all files of filetype 'ROU', and
                with the initial letter of the filename as 'Z'.
     *.GLO     would include all files with filetype 'GLO'
     Z*.*      would include all files with the initial letter of
                the filename as 'Z'
     *.*       would include all files in the file system

In this way you can deal with logical groups of files with one command,
instead of typing each exact file name.

Communicating between MUMPS and the Kermit-M file system

Since Kermit-M files are what Kermit actually sends and receives, we need some
way to get information in these files to and from MUMPS data structures,
namely, routines, globals, and sequential files.  This is accomplished by the
INPUT and OUTPUT options within the MUMPS command of Kermit-M.

Accessing Kermit-M

There is a separate copy of Kermit-M, including data files, in each UCI in
which it resides.  Currently, these are : MGR on both systems, ETA (A) and ETB
(B).  There is a copy in TSA (A); however, this may be a different version
than the others (as TSA is the test location).  You must get the data you wish
to transfer to or from one of these UCI's, preferably, ETA or ETB.

Call Kermit-M by signing into a UCI in direct (programmer) mode and:

     >D ^ZKR

When you see the prompt:

     Kermit-M>

you are at the command level.  Enter commands using TOPS-20 style (this is for
consistency with other Kermits), which is considerably different that the
usual MUMPS style.  You can enter entire commands, ending with <CR>.  Or, you
can enter the command in parts, ending each section with <ESC>; Kermit-M will
complete as much of the command as it can and prompt you for more.  You can
enter '?' at any point in the command to see possible completions.

One of the commands is MUMPS.  This invokes the Kermit-to-MUMPS interface
subprogram, which is organized as a series of menus in conventional MUMPS
interactive style.  (This command is not necessary or available in other
Kermits.)  Here is an overview of the functions and commands in Kermit-M:

Kermit-M>

    EXIT or QUIT   -- leave Kermit
    HELP           -- information
    SEND           -- send files to another machine
    RECEIVE        -- receive files from another machine
    SERVER         -- take all commands from another machine, e.g.
                       to send or receive files
    GET,FINISH,BYE -- commands for a remote Kermit server
    SET            -- set up to communicate with other systems
    CONNECT        -- connect to another machine
    SHOW           -- show the current values of SET parameters
    STATISTICS     -- statistics about the most recent transfer
    MUMPS          -- enter the Kermit-M file system and the
                       Kermit-M <--> MUMPS transfer options

within the MUMPS command:

 DIRECTORY of Kermit-M files
 COPY         Kermit-M files
 RENAME       Kermit-M files
 ERASE        Kermit-M files

 INPUT options (Kermit-M files --> MUMPS data structures)
   1. sequential file in (e.g. print, write to tape or SDP)
   2. routine input (micro-MUMPS routines)
   3. routine input (like %RI)
   4. global input (like %GI)
   5. sequential global input

 OUTPUT options (MUMPS data structures --> Kermit-M files)
   -- inverse of choices 1 to 5 of INPUT options

               Adapting Kermit-M to different implementations of MUMPS



Introduction
      Kermit-M is an implementation of the KERMIT file transfer program written
in 1982 ANSI Standard MUMPS.  It uses most of the new language features in the
1982 Standard, including SET $PIECE, subscript indirection, two-argument
$PIECE, $EXTRACT, and $ LENGTH, extended pattern matching, and fixed-length
READ.  It would be a tedious job to translate to the 1977 Standard or
non-standard versions of MUMPS.  Even within the 1982 Standard, there are many
implementations, all of which differ in some important ways for the Kermit
implementor.  This document explains how to adapt the Kermit-M implementation
for your specific MUMPS.

Limitations on terminal I/O for all versions
      Your MUMPS must implement the single-character READ and WRITE commands to
terminal lines as follows:

     READ *A  -- 'A' must be returned as the decimal value of the ASCII
                 character read, e.g. CTRL/C is returned as 3.
                 All 128 7-bit codes (0-127) must be readable.

     WRITE *A  -- 'A' must be the decimal ASCII value of the character
                  to be written (inverse of READ *).
 The MUMPS standard does not state what values are returned by a READ *, nor
what values are expected by a WRITE *.
      In addition, your MUMPS must support the fixed-length READ (which is
standard):

     READ A#COUNT  -- read COUNT characters into variable A as
                      text; no explicit terminator of the READ
                      is necessary.

Finding implementation-specific code
      All code that depends on the implementation of MUMPS should be commented
at the end of each such line with the comment:

     ;** version

where 'version' is a mnemonic for the MUMPS implementation, e.g.  'M/11 V5'
for InterSystems M/11, version 5.  There is always at least one other version
of the same code, immediately following any 'version' code, which is commented
as:

     ;** STD

This means that this code will run on any MUMPS implementation.  Note that it
might not do anything useful.  For example, to open a communications port
without echo, the code might be: we might have something like:

     O TTY:("":"S") ;** M/11 V5
     ;open port TTY without echo ;** STD

In this case, there is no standard way to turn off echo on a port, so we just
you must write your own.

Altering the code for your version

The code for all implementations except the one you're actually running is
commented out at the beginning of each such line.  So, locate all lines
including the ;** construct, comment out our lines, and remove the comments
from the lines for your version.  In some cases, you'll have to write detailed
code.

Other variations in I/O

1) Input and output buffer size

When running at high input speeds, incoming packets must be limited to no
longer than the length of the system's input buffer.  For example, in M/11 V5,
the default input buffer length for terminal lines is 64 characters; this is
the maximum packet length at high speeds (at 1200 Baud, the program usually
empties enough of the buffer to allow maximum length, i.e. 94, packets).  The
Kermit protocol does not specify any flow control mechanism (e.g. XON/XOFF),
so there is no way for MUMPS to inform the other Kermit that the input buffer
is about to overflow, which is how this problem is usually solved in ordinary
terminal I/O.  You can use the SET RECEIVE PACKET-LENGTH command to do this;
for a more permanent fix, alter the code in INITPAR^ZKRUM which sets the
initial value of RPSIZ.

The size of the output buffer is not usually a problem, since most operating
systems will suspend a program that tries to do output to a full output
buffer, until there is room in the buffer.  If not, use the SET SEND
PACKET-LENGTH command to set the default output packet size.  Note however
that the other Kermit can request a different maximum; you might have to use
SET RECEIVE PACKET-LENGTH on the other Kermit.

2) Image mode and terminators

You must ensure that the SOH character is passed thru the operating system to
Kermit.  The default SOH is CTRL/A (ASCII 1); if there is a problem with this,
the user can SET RECEIVE START-OF-PACKET and SET SEND START-OF-PACKET as
necessary; or for a more permanent fix, the code in INITPAR^ZKRUM can be
altered.

SOH is the usually the only non-printing character sent or received by Kermit.
However, if the other end needs padding (which it will request in its
Send-init packet or its acknowledgement to Kermit-M's Send-init), we must be
able to transmit it thru the operating system.

Setting line parameters
Kermit-M provides several SET options that must be implemented in a
system-specific manner.  These include SET PARITY, SET BAUD, and SET DUPLEX.
Also, local echo is enabled and disabled in a system-specific manner, and the
OPEN, CLOSE, and USE commands are implementation-specific.

In some systems, it may not be possible to change parity or baud from within
MUMPS; these options should be removed, either by changing ^ZKRX("COMMAND"...)
or giving messages like 'can't do that on this system' when trying to execute
the command in routine ZKRSET.

In M/11 V5, the parity, 8-bit data, and baud can only be set by a program
running in the system manager's UCI.  Routine ZKRTC, which provides these
functions , must reside in this UCI (along with the rest of Kermit).
Alternatively, if Kermit is to reside in another UCI, routine ZKRTC must be
moved to the system manager's UCI and renamed %ZKRTC, and the calls to ZKRTC
(at TTYON+1^ZKR and ZKRC+5^ZKRC) must be modified to call %ZKRTC.  You will
have to write an analogous routine for other systems.  In MUMPS running under
other operating systems, you can probably perform these functions with system
calls.