Add README.md

[pdp8.git] / sw / kermit / k12 / k12mit.ann

Date: Sat, 11 Jul 92 15:00:00 EDT
From: Charles Lasner <lasner@watsun.cc.columbia.edu>
Subject: A few more release files for Kermit-12

    Now available are two new versions of K12DEC and K12ENC, which
have a new feature for image transfer of an entire device optionally
split into two parts.  This comes at the request of a user, and was
quite easy to add.  As before, the sources document how to use the
programs, etc.

    The new files have been installed in the regular places:

BITNET/EARN       Internet
KERMSRV@CUVMA     watsun.cc.columbia.edu     Description

 K12MIT   ANN      kermit/d/k12mit.ann        Announcement of KERMIT-12
 K12MIT   UPD      kermit/d/k12mit.upd        Release update (this) file
 K12ENB   PAL      kermit/d/k12enb.pal        .BOO-format encoding program
 K12DEB   PAL      kermit/d/k12deb.pal        .BOO-format decoding program
 K12MIT   NOT      kermit/d/k12mit.not        Release notes file
 K12MIT   DSK      kermit/d/k12mit.dsk        Description of RX02 diskettes

------------------------------
Date: Wed, 11 Mar 92 15:52:25 EST
From: Charles Lasner <lasner@watsun.cc.columbia.edu>
Subject: A few more release files for Kermit-12

    Now available are two new versions of K12DEC and K12ENC, which
have a new feature for image transfer of an entire device.  This
comes at the request of several users, and was quite easy to add.  As
before, the sources document how to use the programs, etc.

    I am working on an upgrade (specifically a handler) for OS/278 to
allow complete transfer of RX50 diskettes as an encoded ASCII-fied
file.  This utility merely handles records available to the normal
file structure, but in the OS/278 RX50 case (from DEC) this is not
the entire disk structure.  In part this is a safety feature, so you
can't access the "slushware" tracks; you can't transfer an entire
image of an RX50 currently.  When the system is upgraded with a
suitable handler, the encoder and decoder gain access to the entire
device; all other system utilities can utilize the entire RX50 as an
effectively larger device.

    If the handler project takes too long (it is actually quite
involved surprisingly enough) I will possibly resort (by popular
demand) to releasing an interim program that does its own RX50 I/O as
a special case of encode and decode.  That would be withdrawn later
when the handler is available.  (DECmates are becoming available to
various people around the world, but they don't have the support
software to get it running; this method would allow them to get their
machines up after they had merely an OS/278 bootable disk (available
from DECUS) and the Kermit-12 files :-).)

    The two new utilities are currently useful for other devices.
For example, an entire OS/8 RX01 or RX02 can be encoded as a file.
With the WPS-oriented handlers installed (commonly available), images
of an RX01 WPS document disk can be encoded/decoded directly.  (This
even includes bootable WPS RX01 systems diskettes, or even RT-11 RX01
disks!)  The existant WPS/COS-style handlers allow transfer of any
RX01 as long as track zero can be ignored.  This is generally the
case on RX01/02, but NOT RX50, thus the above problem.

    The new files have been installed in the regular places:

BITNET/EARN       Internet
KERMSRV@CUVMA     watsun.cc.columbia.edu     Description

 K12MIT   ANN      kermit/d/k12mit.ann        Announcement of KERMIT-12
 K12MIT   UPD      kermit/d/k12mit.upd        Release update (this) file
 K12ENB   PAL      kermit/d/k12enb.pal        .BOO-format encoding program
 K12DEB   PAL      kermit/d/k12deb.pal        .BOO-format decoding program

------------------------------
Date: Mon Oct 21 1991 12:00:00 EDT
From: Charles Lasner <lasner@watsun.cc.columbia.edu>
Subject: Release of Additional Kermit-12 Utilities
Keywords: .BOO, PDP-8, PDP-12, VT-78, DECmate, OS/8
Xref: DEC PDP, See PDP

    This is a release of companion utilities to KERMIT-12 for the
purpose of enhancing file distribution.  Two areas are addressed:  1)
Initial program acquisition,  2) Binary file encoding.

1)  Utilities are provided to create and load copies of KERMIT-12 "on
the fly" from a server such as a remote time-sharing system or a
local PC on the other end of a "clean" connection to the PDP-8.

    Unfortunately, most PDP-8 family systems lack a communications
predecessor to KERMIT-12.  Most communications applications were
limited to terminal emulation only, so it is rare that any PDP-8
system has an existing utility sufficient to acquire KERMIT-12.  (Of
course some sites have prior versions of KERMIT-12 already.)

    Assuming an error-free serial connection to the other system, it
is possible to down-load KERMIT-12 directly into the PDP-8 memory
without a protocol.  This is similar to the process used for years by
DEC field service to load paper-tape copies of diagnostics.  Loading
is limited to a single PDP-8 field at a time.  Performing several
load operations yields intermediary image files which can be combined
into K12MIT.SV identical to the release version (except for
irrelevant loading artifacts which is a consequence of the operating
system itself).

    The format chosen for Initial Program Load (.IPL) is an encoding
that yields ASCII files that should pass through any system with
ease.  The scenario of loading is assumed to be either direct
system-to-system, or between a remote system and one of its
terminals.  All control characters (such as CR and LF) are ignored,
thus the encoded files contain frequent line breaks to make the
encoded file pallatable to the serving system.  Strictly lower-case
letter messages are added at the beginning and end of the file to
serve as leader trailer fields as well as file documentation.  Please
note that while spaces are insignificent, the rest of the ASCII
character set is used for loading information, so editing of .IPL
files must scrupulously avoid changes to the "body" of the file.

    A simple program (K12IPL.PAL) is provided for .IPL loading of a
single field.  The user must customize it for local requirements, and
then enter two variant forms of the loader. (Future releases could
require additional variants to be created.  The current release
occupies two fields.)  This process is similar to customizing the
communications requirements of KERMIT-12 itself.  The program is
sufficiently small to allow manual entry into the system debugger
(ODT) directly.  Examples of such an entry session are provided as
K12IP0.ODT and K12IP1.ODT.  The source program may also be retyped by
any available means (TECO, EDIT, etc.) if desired.  Only standard
PDP-8 peripherals are supported such as KL8E, KL8-JA, etc., as
opposed to KERMIT-12 itself which supports various DECmate
communications hardware as well.  It was felt that the greatly
increased complexity of supporting the DECmate communications ports
would make this process too unwieldy.  However, it is possible to
load the data through the DECmate's printer port.  The VT-78 and all
prior PDP-8 models are fully supported.

    Distribution files include K12FL0.IPL and K12FL1.IPL which are
the encoded copies of field zero and field one respectively.
K12IPL.DOC is a discussion of the .IPL encoding format itself.
K12IPG.PAL is the utility used to create K12FL0.IPL and K12FL1.IPL
from the standard release file K12MIT.SV. (K12MIT.SV is itself
distributed in encoded form as K12MIT.ENC and now also K12MIT.BOO
(see below).  K12IPG can be used with other programs for similar
purposes if required.)

2)  Utilities are provided for encoding and decoding arbitrary OS/8
files using the popular .BOO format encoding scheme.  .BOO format
should be compatible across dis-similar systems thus avoiding
intermediary "hazards."

    While quite popular in the MS-DOS world for file distribution
purposes, .BOO format as originally designed has an inherent weakness
that makes reliable use on OS/8 family systems impossible.  I have
designed an extension to the format to make .BOO format sufficiently
reliable to allow implementation of an encoder and decoder for OS/8
systems.  Note that ENCODE format is still the format of choice for
file distribution because of its more robust nature, but the shorter
files created by a .BOO encoder may be desirable in certain
circumstances.  .BOO format files cannot pass through WPFLOP "paths"
to distribute files on DECmates or VT-78, so ENCODE format is
mandatory on systems used this way.

    The relevant problem with .BOO format has to do with file length
anomalies that are a consequence of the format itself.  .BOO files
either end on a repeat compression field or a complete three-byte
data field expressed as four characters, each only six bits
significant.  Should a file end with only one or two eight-bit data
bytes, two or one additional null bytes will be appended to pad out
the last data field.  This leads to files that are one or two bytes
longer than intended.  At least this is the behavior on systems like
MS-DOS which maintain a file byte count.  Since OS/8 files are
multiples of whole records, each of which can be viewed as a
collection of 384 bytes, any change in a file's length of even a
single extra null byte will cause the creation of an extraneous whole
record.  Besides wasting space, it is conceivable that an OS/8 file
corrupted in this manner could actually be dangerous to use!  Note
also that this problem can be cumulative in that repeated
transmission between systems where the file is stored locally in some
decoded form, and then encoded locally before transmission to another
site, can cause the problem to worsen indefinitely.  Clearly, .BOO
format must be firmed up to prevent this form of file corruption
before it can be used safely on PDP-8 systems.  (It has also been
noted that widely distributed .BOO encoding programs exist on certain
systems which exhibit defects such as erroneous appendage of
additional null bytes onto the end of the file not indicated by the
file's contents.  This is clearly a program bug and not an inherent
problem with .BOO format design.)

    The method chosen to correct the existing .BOO anomaly is to
append a correction field to the end of every file requiring it.  The
basic correction unit is ~0 which means literally a repeat
compression field with a count of zero.  This construct is ignored by
most .BOO decoders because it contributes nothing to the file. (At
the bare minimum, .BOO decoders should implement the robustness of
ignoring this type of data.  It is conceivable that due to design
error, a decoding program could "blow up" when encountering this
data.  Imagine a file lengthened by 2^32 null bytes!  The exact
amount of extraneously generated null bytes would likely be 2^{how
many bits wide are integers on the machine} or one less than that.)

    .BOO-encoded files may now contain either ~0 or ~0~0 at the end
to indicate whether one or two bytes are to be "taken back"
respectively.  Tests on MSBPCT.BAS and MSBPCT.C as currently
distributed by CUCCA indicate that these corrections are perfectly
ignored, thus decoded files are erroneously inflated by one or two
bytes.  This is the expected behavior of these older decoders.  When
used with PDP-8 DEBOO.SV (distributed in source form as K12DEB.PAL),
the correct file length is maintained.  PDP-8 ENBOO.SV (distributed
in source form as K12ENB.PAL) is the first encoding program that
creates the correction field as necessary.  It is hoped that this
"pioneering" effort will cause other systems' encoders and decoders
to be similarly updated.

    Overall program operation for the encoder and decoder is
identical to the equivalent programs for ENCODE format.
Documentation is contained in the source files.  As in the ENCODE
format decoding program, the target file name can be taken from the
original file name imbedded within the file, or optionally the user
can specify a target file name as well as a target device.  When
encoding, the imbedded file name will always be the original name of
the file supplied as input to the encoder.  The user can specify any
valid combination of output file name and device for the resultant
encoded file.

    OS/8 files passed through ENBOO/DEBOO are packed/unpacked
according to the standard OS/8 "3 for 2" scheme to ensure byte
accuracy where relevant.  This allows files which are ASCII, but too
"delicate" for ordinary transfer to be sent between unlike systems
with total accuracy.  This includes any file where the precise
placement of CR and LF may be critical, or contains unusual
characters in the file such as BEL or ESC.  A perfect example of this
is the interchange of TECO macros between PDP-8s (used with OS/8
TECO.SV) and IBM-PCs (used with MS-DOS TECO.EXE) with a unix system
as an intermediary storage site.  Both end systems use like line
termination schemes incompatible with the intermediary system.  Since
both systems support .BOO format, the files can still be sent without
loss.

    Most of the existing K12MIT-related files are unchanged.
K12MIT.DSK is updated to reflect all new files pertaining to .IPL or
.BOO utilities.  K12MIT.ANN and K12MIT.UPD are updated per this
announcement.  All files distributed in ENCODE format are replicated
in .BOO format.

    The new files have been installed in the regular places:

BITNET/EARN       Internet
KERMSRV@CUVMA     watsun.cc.columbia.edu     Description

 K12MIT   ANN      kermit/d/k12mit.ann        Announcement of KERMIT-12
 K12MIT   UPD      kermit/d/k12mit.upd        Release update (this) file
 K12MIT   DSK      kermit/d/k12mit.dsk        Description of RX02 diskettes
 K12MIT   NOT      kermit/d/k12mit.not        Release notes file
 K12IPL   PAL      kermit/d/k12ipl.pal        .IPL loading program
 K12IP0   ODT      kermit/d/k12ip0.odt        ODT session creating IPL0.SV
 K12IP1   ODT      kermit/d/k12ip1.odt        ODT session creating IPL1.SV
 K12FL0   IPL      kermit/d/k12fl0.ipl        .IPL encoding of K12mit (FL0)
 K12FL1   IPL      kermit/d/k12fl1.ipl        .IPL encoding of K12mit (FL1)
 K12IPG   PAL      kermit/d/k12ipg.pal        .IPL-format encoding program
 K12IPL   DOC      kermit/d/k12ipl.doc        Description of .IPL format
 K12ENB   PAL      kermit/d/k12enb.pal        .BOO-format encoding program
 K12DEB   PAL      kermit/d/k12deb.pal        .BOO-format decoding program
 K12MIT   BOO      kermit/d/k12mit.boo        .BOO encoding of KERMIT-12
 K12PL8   BOO      kermit/d/k12pl8.boo        .BOO encoding of PAL8 Ver B0
 K12CRF   BOO      kermit/d/k12crf.boo        .BOO encoding of CREF Ver B0
 K12GLB   BOO      kermit/d/k12glb.boo        .BOO encoded TECO file macro

[Ed. - Thanks, Charles!  Additional information can be found in the new
file, k12mit.not (K12MIT NOT), a message from Charles to the "PDP-8 lovers"
mailing list.]

------------------------------
Date: Thu Sep 6 1990 11:00:00 EDT
From: Charles Lasner <lasner@watsun.cc.columbia.edu>
Subject: Announcing  KERMIT-12 Version 10g
Keywords: PDP-8, PDP-12, VT-78, DECmate, OS/8
Xref: DEC PDP, See PDP

    This is a maintenance release of KERMIT-12.  A minor problem
relating to incorrect CPU identification messages has been fixed.
The problem only appeared when the CPU was a KK-8A single-board CPU;
this configuration was previously untested.  Thanks to Johnny
Billquist of Sweden for his assistance in pinning down the problem.

    KERMIT-12 operation was not affected in any other way, as only
the DECmate-specific identification is crucial; earlier PDP-8 family
members are treated in a generic fashion except for the "frill" of
model identification (all PDP-8, PDP-12, VT-78 models use
software-compatible port hardware;  all DECmates are incompatible and
must be handled individually).  We are still looking for volunteers
to test the various DECmate III and DECmate III+ configurations.

    The rest of the release concerns the encoding of files into the
"ASCII-fied" format.  The format has been modified to be more robust,
since the original method has proven itself to be problematic in
certain practical circumstances (as reported in K12MIT.BWR).

    The new ENCODing format is based on five-bit encoding with repeat
compression.  As much as 256 repeated 12-bit words will be expressed
in a five character field.  Any repeated 12-bit value can be
compressed, as opposed to simple zero compression, as in other common
encoding schemes.  (PDP-8 files often have repeated strings of the
value 7402 octal, which is the HLT instruction.)

    The only printing characters required to pass through any
distribution "path" are 0-9, A-V, X, and Z. The alphabetic characters
can also be lower-case.  All command lines are framed by ( and );
all data lines are framed by < and >.  These characters can be
changed if required, as they are not part of the data; they could be
replaced by W (w) and Y (y) if necessary.  (Changing the framing
characters requires slight modification of the ENCODing and DECODing
programs.)

    The new format supports a 60-bit file checksum to ensure proper
decoding at the other end.  The former 12-bit checksum could be
compromised on long files.

    The new ENCODing programs creates internal (REMARK commands
stating the ENCODed file's creation date, and the original file's
creation date.  This will aid in distribution of PDP-8 files where
the user wishes to maintain proper file dates.  The date algoritm
used is the one proscribed by the OS/8 DIRECT program. (OS/8 systems
only OPTIONALLY support file dates, and there is an eight-year
"anomaly" associated with identifying the year; the user must
determine the credibility of the year portion of the date.  The value
provided by the ENCODE program for the original file creation date is
always today's year or the previous seven years as necessary; this
field will not be provided if the system doesn't support the required
AIW feature.)

    Overall file size is theoretically as much as 6/5 of the original
encoding format (as the earlier format was based on six-bit
encoding), but actual size varies downward due to slightly less file
overhead (wider lines mean less CR LF; there is now less
automatically generated verbiage), and the random improvement
afforded by simple repeat compression.

    Virtually all K12MIT-related files are re-released at this time.
There are several new files.  Due to the "fragile" nature of TECO
macro files, the file K12GLB.TEC is no longer being distributed
directly; the file K12GLB.ENC is the same file in the new ENCODE
format.

    The new files have been installed in the regular places:

BITNET/EARN       Internet
KERMSRV@CUVMA     watsun.cc.columbia.edu     Description

 K12MIT   ENC      kermit/d/k12mit.enc        Encoded binary of KERMIT-12
 K12MIT   DOC      kermit/d/k12mit.doc        Documentation file
 K12MIT   BWR      kermit/d/k12mit.bwr        Updated "beware" file
 K12MIT   DSK      kermit/d/k12mit.dsk        Description of RX02 diskettes
 K12MIT   ANN      kermit/d/k12mit.ann        Announcement of KERMIT-12
 K12MIT   UPD      kermit/d/k12mit.upd        Release update file
 K12DEC   PAL      kermit/d/k12dec.pal        Decoding program
 K12ENC   PAL      kermit/d/k12enc.pal        Encoding program
 K12PL8   ENC      kermit/d/k12pl8.enc        Encoded binary of PAL8 Ver B0
 K12CRF   ENC      kermit/d/k12crf.enc        Encoded binary of CREF Ver B0
 K12MIT   PAL      kermit/d/k12mit.pal        Main source file of KERMIT-12
 K12PCH   PAL      kermit/d/k12pch.pal        KERMIT-12 source patch file
 K12CLR   PAL      kermit/d/k12clr.pal        Memory clearing file
 K12MIT   LST      kermit/d/k12mit.lst        Symbols-only listing file
 K12PRM   PAL      kermit/d/k12prm.pal        Sample VT-78 config file
 K12GLB   ENC      kermit/d/k12glb.enc        Encoded TECO file macro
 K12ENC   DOC      kermit/d/k12enc.doc        Encoding format description

[Ed. - Many thanks, Charles.  Believe it or not, there are still quite a
few PDP-8 based systems out there, and even some PDP-12s.  You won't find
very many other new software packages that support them!]

------------------------------
Date: 05-October-1989
From: lasner@cunixc.cc.columbia.edu (Charles Lasner)
Subject: Announcing  KERMIT-12 Version 10f
Keywords: PDP-8, PDP-12, VT-78, VT-278, DECmate, OS/8
Xref: DEC PDP, See PDP

    This is to announce the release and availability of a highly
revamped KERMIT program for the complete family of Digital Equipment
Corporation 12-bit computers, known as KERMIT-12 (or K12MIT), Ver.
10f.  Unlike its predecessors (K08MIT and K278, upon which it is
partially based, as well as prior versions of KERMIT-12), KERMIT-12,
as now distributed, will run on any PDP-8 model (8, LINC-8, 8/i, 8/l,
8/e, 8/f, 8/m, 8/a), PDP-12, VT-78, or DECmate (VT-278, aka DECmate
I, DECmate II, DECmate III, DECmate III-plus) under any OS/8 family
member  operating  system.  Proper operation is accomplished
automatically.  Companion utilities are provided to deal with
"ASCII-fied" binary files in ENCODE format (a mechanism designed by
Charles Lasner and Frank da Cruz as a proposed successor to BOO
format); ENCODE format has been employed to distribute the binary
portion of this release of KERMIT-12.

    Due to the myriad port requirements of the various models,
conditional parameters have been provided in the source (as well as a
separate patching file) for models prior to DECmate I.  The program
auto-configures for all models of DECmate;  parameters are available
to select the DECmate ports (DP278, communications, printer, etc.)
where applicable.

    Many improvements have been provided to get this KERMIT "up to
speed" relative to other KERMITs.  KERMIT-12 has been tested
successfully with many KERMIT implementations and will run at the
maximum baud rate (and sometimes beyond the DEC-stated limit!) of the
relevant interface.  Any console terminal configuration acceptable to
OS/8, etc. can be used at any baud rate as long as local flow-control
protocol is obeyed; remote flow control can be disabled at console
speeds higher than the remote line rate.  Connect mode I/O is fully
ring-buffered in all directions with local flow control always
enabled for all console terminal operations.  (This should satisfy
all console terminal requirements ranging from 110-baud teletypes to
built-in 350-Kbaud VT-220 emulators, since any of the gamut of these
ASCII terminals could be the system console terminal for any of the
KERMIT-12 supported computer configurations!).

    KERMIT-12 will run anywhere OS/8 does, so it runs on any perfect
look-alike suitably configured.  Some known compatibles are:

  - TPA made in Hungary, this machine is an 8/l except for the silkscreened
    letters which are Magyar, not English.
  - Fabritek MP-12
  - Intersil Intercept
  - Pacific CyberMetrix PCM-12
  - Digital Computer Controls DCC-112 and DCC-112H
  - Computer Extensions CPU-8 (a drop-in replacement for the 8/e or 8/a cpu
    for a PDP-8/A-400 or -600 hex-wide box)
  - Computer Extensions SBC-8 (a single-board computer -8 compatible based
    on the 6120 like a DECmate, but compatible with -8 peripherals, not
    DECmate peripherals; it also supports up to 16 comm ports)

    Various emulators are available for PDP-10, 15 and the IBM-PC
which will also support KERMIT-12 if suitably configured.

    Distribution files are available from CUCCA.  Testing is under
way for some of the more obscure configurations (e.g., DECmate III
with comm port); volunteers are welcome for this task.  The author
can provide copies to interested parties on virtually all of the
popular PDP-8 media on a time-available basis.

[Ed. - Many thanks, Charles!  The files are in Kermit Distribution area D
with prefix K12, and the previous PDP-8 versions having prefixes K08 and
K278 have been retired.  Internet users may ftp the files as kermit/d/k12*,
and BITNET users can get them from KERMSRV at CUVMA as K12* *.]

------------------------------