The LS-DOS 6.3.1 Source Code Restoration Project - History

	[Copyright 1999,2000 Frank Durda IV, All Rights Reserved.
	This document may not be placed on a Web or FTP site.
	A complete (all files must be transferred unaltered)
	distribution is allowed, read the document for details.

	The official web site is http://nemesis.lonestar.org
	Contact this address for use clearances: clearance at
	nemesis.lonestar.org    Comments and queries to this
	address: web_software at nemesis.lonestar.org]

	Last updated 12-Mar-2000

LS-DOS is an operating system created for use on the Tandy Model 4, 4P and
4D computer systems.  A port was also developed for the Tandy Model II/12
computer systems but this was never seriously exploited.  LS-DOS was
originally developed by Logical Systems, and it is a descendant of the
LDOS operating system which was sold for Tandy/Radio Shack  Model I and
Model III computers.

Originally sold under license to Tandy Corporation using the name TRSDOS 6,
approximately 400,000 Model 4, 4P and 4D computer systems came with
TRSDOS 6, and there were numerous upgrade releases between 1983 and 1990.
Around 1986, Logical Systems began to sell the operating system directly to
Tandy/Radio Shack customers and at that time the software name was changed
from TRSDOS 6 to LS-DOS 6.3.  A later version called LS-DOS 6.3.1 was
marketed by MISOSYS, a company formed by a former partner of Logical
Systems.

The LS-DOS 6.3.1 operating system source code that is presented here exists
only because of the result of the fortunate recovery of the source code for
LS-DOS 6.3.0, along with a restoration effort to make that source code
produce the 6.3.1 release, the source code for which had been lost.

A history of the relations between Tandy and Logical Systems that led to
this distribution surviving at all is presented below, along with a
discussion of how the restoration was performed and verified.


Background on LSI vs Tandy and the creation of 6.3.0.

During the years Logical Systems (LSI) provided TRSDOS 6 to Tandy
Corporation, LSI and the Computer Merchandising "product" buyer at Tandy
were frequently fighting.  At one point, the arguing and distrust got so
bad that LSI refused to communicate with anybody at Tandy Corp, except
Frank Durda IV.  Although Frank worked for Tandy Corp, Bill Schroeder of
LSI trusted Frank more than anyone else at Tandy Corp that LSI was dealing
with.  Tandy was not happy with this arrangement and at one point Tandy
started intercepting Franks US Postal mail, just to see what was going on
between Frank and LSI.  Despite this and other nonsense, the arrangement
kept bug fixes and new OS releases coming from LSI, such as TRSDOS 6.1.x,
6.2.0 and eventually 6.3.0.

When 6.3.0 was under secret development at LSI (LSI elected to not tell the
Tandy buyer anything about the work), the current Tandy buyer for the
Model 4 product line had already abandoned the Model 4 products to their
fate by pulling all advertising, hoping interest in the product would
die-off.  However, the concerns/complaints about not having an OS upgrade
for the existing customers that would work past 1987 was a problem he was
unable to ignore, despite the buyer telling Radio Shack stores at one point
to recommend Tandy 1000 purchases to concerned customers.  That plan
backfired and resulted in many letters to the president of Radio Shack and
the CEO of Tandy.  Eventually, the product buyer at Tandy was forced to
tell LSI that Tandy was "somewhat" interested in a patch or something that
would get systems past 1987, maybe to 1990.  Again, the Model 4 product
buyer, who happened to also be the buyer for the Tandy 1000 line, really
wanted the Model 4 and related products to just die and disappear, so
extending its life by only three years seemed reasonable to him.  He really
wanted all 400,000 Model 4 family users to migrate over to Tandy 1000s.

LSI responded, saying there would be no patches, only a new and full OS
release that they had been developing and that LSI would sell directly.
Tandy could sell copies if they wanted to, but Tandy would have little or
no control over the release.  Of course, most of that suited the buyer at
Tandy who didn't like the Model 4 anyway, so the deal was worked on *one*
condition.

The customer support groups of Tandy voiced persistent concerns that if LSI
was to go out of business, Tandy would be unable to support existing
customers, or legally provide customers with copies of the OS, such as to
replace damaged copies or to upgrade people who waited until 1988 and then
discovered that they had a system that they could no longer use.  The buyer
thought that having the system "orphaned" on the software side as well was
a big plus, as it would just push more frantic people over to his Tandy 1000
line, but he was eventually forced into honoring the demands from the Tandy
customer support groups and to negotiate this point with LSI.


Why this source code tree exists today

The agreement reached between Tandy and LSI for letting LSI sell 6.3.0
on their own with Tandys blessing (Tandy sent a letter to all registered
Model 4/4D/4P owners telling them where to get 6.3.0) was that LSI would put
a copy of the source code to the operating system into a trust or an escrow.
If LSI ceased to exist and Tandy System Software needed the code to support
the operating system, Tandy could obtain the code from the trust and
maintain the code themselves.  There were some other clauses - time limits,
no transferability, etc - but the bottom line was that Tandys software
development group could get the code if they needed it, but only if there
was no one else to support it.

Possibly to annoy the buyer at Tandy, LSI selected Frank Durda IV as the
executor of the trust, kind of a strange thing to do considering that he  
still worked for Tandy.  Tandy blinked and then agreed, probably figuring
they could threaten Frank with his job if they needed the code later on, if
the conditions allowing their access to the trust had not been met.
A short time later, Bill sent Frank the code that made up LS-DOS 6.3.0, or 
at least as it stood at that time.  Some changes were made to 6.3.0 after 
that point which was before 6.3.0 release went public, but the code is
fairly close.  The code went to a closet in Franks house and remained there
largely ignored for several years. 

As it turned out, the documentation for LS-DOS 6.3.0 was also edited and
typeset by Frank Durda IV since he had access to typesetting software
(troff) and an Apple laser printer, something that LSI didn't have right
at hand.  Frank also contributed a new MODELA/III file to the release that
he had developed which Tandy had taken no interest in.

The trust ends when Tandy Computers goes out of business first

As time went by, LSI licensed the right to sell LS-DOS to Misosys, who
continued to support LS-DOS and in 1990 offered a new release, LS-DOS 6.3.1
which contained minor refinements to the system.  Over the next year,
several patches were also published to 6.3.1.   Misosys continued to
support LS-DOS until around 1994, when they closed their doors.  

Meanwhile, Tandy computers gambled on entering the TV set-top "edu-tainment"
game market, thinking they could beat Sega and Nintendo at their own game,
using a Microsoft-designed platform called Modular Windows (later renamed
Windows CE and in 1999, Microsoft announced that due to sagging sales, they
were going to rename Modular Windows yet-again.)  When Microsoft
double-crossed Tandy by making Modular Windows 1.1 incompatible with 1.0
immediately after the 1.0-based VIS game system was sent to be manufactured,
Tandy lost millions on the system that they had to sell well below cost.
About the same time, Tandy also lost several manufacturing contracts,
including one where they made PCs for Digital Equipment Corporation, work
that was using 40% of Tandys factory capacity.  At the peak of these
troubles, Tandy elected to spin-off the computer design, manufacturing and
software groups who were under the Tandy Electronics division (TE) into
a new free-standing company, TE Electronics, (aka Tandy Electronics
Electronics).  This spin-out never got off the ground, and within four
months Tandy announced the cancellation of the spin-off and the fact that
the computer division was now being sold to AST Research, a California-based
PC maker.  On July 1st, 1993, Tandy left the computer business, and the
Tandy System Software department ceased to exist, terminating the trust
between LSI (now Misosys) and Tandy.  As it turned out, Tandy left the
computer business before Misosys did.

Of course, by 1993 the buyer who hated the Model 4 so much had left Tandy,
and Tandy support had stopped answering questions on the Model 4 years
before that, so probably no one considered or cared what happened when the
trust terminated.  When Tandy originally agreed to the trust, they agreed
to it being non-transferable, the same lack of foresight that cost AST
access to the PC-BIOS that Tandy had purchased from Phoenix back in 1984, a
deal that was essentially royalty-free to Tandy, but not to AST.

Despite the termination of the trust, the diskettes stuck in the back of
that closet still contained copyrighted material that still belonged to Bill
Schroeder even after Misosys closed its doors, so Frank could not simply
make it available when people on the Internet started asking about this in
1996.  Then in 1997, it was announced that Roy had released to the public
domain all software that Misosys had created or obtained the rights to.
This included software from Powersoft and LSI.  Roy later clarified this
claiming he didn't really mean to put everything in the public domain but
was willing to make material "publicly available" without royalty or
license.  In November of 1998, in a telephone call to Bill Schroeder, Bill
indicated that he still held the copyright to LS-DOS itself, and was
releasing that code to the public domain.

So, LS-DOS 6.3.x was now in the public domain.  Unfortunately, in the
intervening years, Roy had misplaced his source code for 6.3.1 and could not
find it, although some re-surfaced in 1998.  A check with Bill Schroeder
found that he had also discarded the source code he had some time earlier
and no longer had a copy.   The source code to TRSDOS 6.2.0 was available
in book form, but scanning and then updating that three-volume publication
would be a massive project and would never accurately reflect the real
assembly and master diskette building processes involved in building any
of the TRSDOS/LS-DOS operating systems.  That meant that the only known
surviving complete electronic copy was sitting in the bottom of a closet
in Fort Worth Texas.

Therefore, Frank Durda IV undertook a project to take the almost-6.3.0
source tree that he still had, and bring it up to date so that it produced
code identical to what came on a LS-DOS 6.3.1 binary diskette from Misosys.

The entire project took about seven months with spurts of work, with 
approximately 450 hours going into the project.  Despite the effort
involved, Frank Durda IV hereby releases the output of this restoration
project for any use with only two restrictions:  

	The /TXT version of this file must remain intact in any electronic
	or other distribution of any part of this release, and

	No part of the distribution or a derivative work may be placed on
	any other web or FTP site without prior written permission.  The
	files created as part of this reconstruction and of the official
	web site are copyrighted.



How the pre 6.3.0 Source Tree was restored and synchronized to match 6.3.1

After successfully getting the entire pre-6.3.0 tree to compile (and
remembering all the commands to do this), each file was byte-compared
against the file present on an original LS-DOS 6.3.1 diskette which had
been obtained from Misosys years earlier.  This diskette turned out to be
patched to 6.3.1 Level-1B.

Although the documentation for LS-DOS 6.3.1 suggested only a handfull of
modules had been changed between 6.3.0 and 6.3.1, almost every module
contained at least one change which had to be disassembled from the image on
the 6.3.1 floppy disk and applied in source form to the appropriate files.
Undoubtedly, the most difficult files to update were the MEMORY command,
the CONV utility, and DOS/HLP.   Many programs had instructions re-arranged
slightly, apparently for coding-style reasons, since the code was executed
so infrequently as to not provide any performance benefit, nor did it make
the module significantly smaller as to fit in fewer sectors on diskette.

A perfect example of this sort of "style" change was the removal of all
periods from sentences in the online help documentation (DOS/HLP), and the
occasional replacement with a semi-colon.  It is not clear why this
improved readability, grammatical accuracy, or made the overall module
smaller in some way that provided significant gain.

In source code, the most common change was a re-work of the first dozen
bytes of the program to save the stack pointer earlier and make the
branching condition be the user-hit-BREAK case instead of the opposite which
was the norm in TRSDOS/LS-DOS.  The next most common change was
changing absolute branches to relative branches to locations where another
absolute branch took the processor to where the original absolute branch
wanted to go.  Next came replacing register initialization from a constant
with initialization from another register that happened to have the right
value.  This latter change had to be "undone" in a few places in subsequent
patches because the other register didn't always have the desired value.

In Franks opinion, approximately 80% of the modules that changed between
the 6.3.0 tree and 6.3.1-1B contained these changes of questionable
value, and identifying all of these and adding them to the source code
took the bulk of the engineering effort on this project.

Each change made to the entire source tree (except documentation*) is
contained within a conditional assembly IF.  In the file BUILDVER/ASM, all
of the changes that bring the code up to 6.3.1-1B can be enabled or disabled
via the equate @BLD631.  This allows the code to be studied and the changes
specific to 6.3.1 can be identified.

* Since the HELPM4F/TXT (source for DOS/HLP) could not be assembled 
  conditionally, the original file as provided for 6.3.0 can be found
  under the name HELPM4F/T30.  This file can only be edited with certain
  editors, as it uses CONTROL-L characters as a directive to the help
  file generator.  The LED62 editor works on this type of file.  The binary
  is provided.

Once the entire source tree compared byte-for-byte to the Misosys 6.3.1
floppy, each patch published in the Misosys Quarterly was added to the
source code.  These patches are also controlled by the BUILDVER/ASM file
and are all within conditional statements.  Because some patches rely on
others, it is important to apply all earlier patches, unless you really
know what you are doing.

Where significant new sections of code were added (LBMEMORY/ASM is the
largest example), no attempt was made to generate comments or meaningful
label names, unless it was immediately obvious what a bit of code did.

In the case of patches, labels for patches are of the format P631pn,
where p is the patch letter and n is the label number in this patch.

Once all patches up to Level 1H are applied, all files in the target
directory exactly match those present on a 6.3.1 floppy from Misosys that
has been patched with the patches listed in the Misosys Quarterly, with
*one* exception: SYS8/SYS.  SYS8/SYS was patched from 1B to 1C with a
patch that extended the size of the SETKI module.  The way this is done
with the PATCH program cannot be precisely duplicated in source code, so 
this one /SYS file will not compare byte for byte.  However, each module
within the SYS8/SYS library (the (LBnnnn/CMD files) does compare exactly.

The end result of this is a set of files as close as practical to the
hand-patched 6.3.1 diskette from Misosys.

The actual Misosys patches are included (FIX631p/JCL), in case you wish
to use them.  They were used dueing the project to verify that the source
code implementation of the patches matched the binary version provided in
the Misosys Quarterly.


Other modules

Also included in this tree is the source code to TRSHD6 and TRSFORM6, the
hard disk driver and formatter prepared for Tandys Western Digital-based
hard disk systems.  Since these were not included in 6.3.0 or 6.3.1, no
changes have been made to these modules, although they do assemble.

Model 4 BASIC is patched during the build process to support the LSI
extensions and load the LSI-specific BASIC/OV2 overlay.  You will find
an unmodified copy of BASIC (BASIC62/CMD) in the drive 3 tree, along
with BASIC62/OV1, which is not altered during the build process.

Also present is the MODELA/III file, the same one distributed with 
LS-DOS 6.3.0 and 6.3.1, as provided by Frank Durda IV.  The German and
French versions (MODELD/III and MODELF/III) originally distributed with
TRSDOS 6.1.2 and 6.2.0 were never included with the LS-DOS 6.3 releases.
Each version of the MODEL%/III file assumes a specific keyboard and other
system hardware.

Several utilities are included that are directly or indirectly used 
during the build process: EDAS, HELPG60, LED62, XREF, GENLIB4, etc.
The source code for most of these utilities was not provided in the
trust distribution, but may be available elsewhere.


About the Model 2

The source tree contains components specific to the Model II/12 version of
LS-DOS.  No attempt has been made to synchronize the source code on these,
and it is probable that the code won't assemble without some work.
Getting the Model II/12 code working simply wasn't on the agenda.


Building the LS-DOS 6.3.1 System

The file BUILD/TXT on the distribution floppies describes all the steps
needed to assemble the system and construct the distribution floppy.


In conclusion

The Model 4 family was manufactured for about five years (1983 - 1987),
and approximately 400,000 total systems were produced by Tandy during that
period.  During its first year of production, it was one of the most-sold
computers on the market, competing strongly against the IBM PC and Apple IIe
computers, particularly in schools, where 30 or 40 Model 4 systems would be
networked together, sharing a single 5 or 12 Meg hard disk drive.

By comparison, the Model 16 and 6000 sales only reached about 100,000 units
combined during their entire production life.  On the other extreme, the
Tandy 1000 sold about 300,000 units in its first year.

Educational purchases kept the Model 4D in the Radio Shack/Tandy catalog
long after individual sales would have caused the system to be discontinued.
Individual sales never disappeared, despite Radio Shack not advertising the
Model 4 family at all (outside of the catalog) after 1984.

On the educational side, the Tandy 1000 educational networks were sold to
schools for over a year that consisted of 30 or 40 Tandy 1000s and a Model
4 that acted as the disk server system, because the Model 4 ran the server
software so much faster than the equivalent version running on a PC and
MS-DOS.  Finally, the Model 4 was replaced by a 16MHz 386-based system that
was fast enough to take over the server tasks and provide equivalent
performance.

Despite the fact that the Model 4 hardware has been out of production for
over ten years now, a small revival continues, mainly using modern PCs and
software to emulate the Z-80 and the Model 4/4D/4P I/O port maps, allowing
these older operating systems and applications to live on.  There is even
occasional talk of building a "modern" Model 4 hardware box, one that
would run hundreds of times faster than the original Model 4 systems ever
did.

As of this writing, there are also still a handfull of companies that sell
parts, software and even complete Model 4/4D/4P systems, as well as
individual owners cleaning out their closets and offering systems for sale
via the Internet.

It is hoped that the effort expended in updating this code and making
it available will prove useful to hobbyists, researchers, and perhaps
someday, even archeologists, as they look into the ancient mysteries of 
personal computing, something that was around years before IBM got into
the game, despite what IBM and Microsoft now claim.

Frank Durda IV,  March 12th, 2000


	[Copyright 1999,2000 Frank Durda IV, All Rights Reserved.
	This document may not be placed on a Web or FTP site.
	A complete (all files must be transferred unaltered)
	distribution is allowed, read the document for details.

	The official web site is http://nemesis.lonestar.org
	Contact this address for use clearances: clearance at
	nemesis.lonestar.org    Comments and queries to this
	address: web_software at nemesis.lonestar.org]

A HTML-formatted version of this document can be found at 
http://nemesis.lonestar.org/computers/tandy/software/os/logical_systems/-
lsdos6/src631

