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 PDP11/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 (PDP11,
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
.MMP
.GLO
.TXT
-----
a set of MUMPS routines, in %RO/%RI format
one micro-MUMPS routine
global references and data, in %GO/%GI format
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
*.GLO
Z*.*
*.*
would include all files of filetype 'ROU', and
with the initial letter of the filename as 'Z'.
would include all files with filetype 'GLO'
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
HELP
SEND
RECEIVE
SERVER
------
GET,FINISH,BYE
SET
CONNECT
SHOW
STATISTICS
MUMPS
-------
leave Kermit
information
send files to another machine
receive files from another machine
take all commands from another machine, e.g.
to send or receive files
commands for a remote Kermit server
set up to communicate with other systems
connect to another machine
show the current values of SET parameters
statistics about the most recent transfer
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 fixedlength
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
system to
Kermit. The default SOH
this,
the user can SET RECEIVE
necessary; or for a more
altered.
SOH character is passed thru the operating
is CTRL/A (ASCII 1); if there is a problem with
START-OF-PACKET and SET SEND START-OF-PACKET as
permanent fix, the code in INITPAR^ZKRUM can be
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.