BLDLIBS/CMD - System Library Command Overlay Builder for LS-DOS 6.3
Version 01.02.06

Copyright 1997, Peter W. Cervasio
All rights reserved.

Standard "free for public use, as long as my copyright notice is neither
removed or changed".  You may not pretend that you wrote it.  If it breaks,
you get to keep all the parts.  While every effort has been made to ensure
that this program operates as documented, it's worth exactly what I am
charging people for it - nothing.

OVERVIEW
========

BLDLIBS is a utility for programmers who like to hack into the system library
commands stored in SYS6/SYS, SYS7/SYS and SYS8/SYS.  Though the Misosys 
package PRO-CESS will extract the individual command files from overlays
SYS6, SYS7 and SYS8, I have not found a utility to create a library file out 
of /CMD files.  Since I have typed the complete source for TRSDOS 6.2 into 
/ASM files, and updated it for version 6.3.1, I really wanted a way to 
re-create the library modules from the re-assembled source.  Once I could do 
that, and get binary files that compare byte-for-byte to the original /SYS 
files, I would feel confident in customizing LS-DOS to my own liking.

BLDLIBS was created to fill just that purpose.  It will allow you to re-create
the standard system libraries from individual /CMD files that have been 
extracted from the originals via the PROCESS utility, or assembled files
from the LS-DOS source release.

BLDLIBS is a little dumb, in that it only knows how to get its information 
from a text file that you create.  Samples for each of the system libraries 
for LS-DOS 6.3.1 have been included in the archive.

DISTRIBUTION FILES
==================

The zip file you received this utility in should have contained the following
files:

      Program files:
      --------------
      BLDLIBS/CMD - The program itself, pre-compiled with PRO-MC
      BLDLIBS/CCC - Source code for the program
      BLDLIBS/TXT - This documentation

      Sample data files:
      ------------------
      L631LIB6/DAT - Data file for SYS6/SYS
      L631LIB7/DAT - SYS7/SYS
      L631LIB8/DAT - SYS8/SYS

INPUT FILE FORMAT
=================

As stated above, the input file specifies all the information required to 
generate a library module.  The filename must be specified on the command line
to BLDLIBS, and all other input comes from that file.  Well, that's not 100%
exactly true, come to think of it.  Other input comes from the /CMD files 
specified in the input data file.  Never mind.

The input file layout is as the following:

Line	Contents			    Description
====    ================================    ==================================
1       Output filename                     For example, SYS6/CMD
2       Base ISAM number                    normally 80, 0A0 or 0C0 - IN HEX!
3       Number of input files               num cmd files to make library from
4       Input filename                      LBLIB/CMD, for example
5       Num entries in this /cmd file)      3, for example
6       ISAM number for command             1E, for example.  (in HEX)
7       TRA address for command             2400, for example (in HEX)
8       ISAM number of next in /cmd file    if more than one
9       TRA address of next in /cmd file    if more than one

        (repeat 6 and 7 for the each of the library commands in the module)

10      next input filename
        next num entries in /cmd file
        etc..
        (repeat 4 through 9 as needed for library overlay)

It is highly recommended that you do not set the output file to SYSx/SYS, but
rather to a /CMD file.  Or some other extension.  This will help prevent any
errors from happening if you happen to have a system disk sitting in your
output drive.  I'm sure the program could be enhanced to allow for this, but
I haven't bothered to take the time to do so.

An example data file might be:

TESTLIB/CMD                     Test filename
80                              Specified in HEX
1                               comprised of one /CMD file
LBLIB/CMD                       A test filespec
3                               Three commands in it
5                               1st one's ISAM # is 85H
2400                            1st TRA Addr is 2400H
8                               2nd one's ISAM # is 88H
2403                            2nd TRA Addr is 2403H
7                               3rd ISAM # is 87H
2406                            3rd TRA Addr is 2406H

The sample files included in the archive with the program are set up to build
the system libraries for LS-DOS 6.3.1, as I sent it to Tim Mann for putting
up on his web page.  The 6.3.1 source code was generated by running the LS-DOS
6.3.1 files through PRO-Duce (and PRO-Cess for the libraries) and then going
through the book and each source file putting in the comments and fixing up
the statement labels.

RUNNING BUILDSYS
================

To run BUILDSYS, just enter it's name, followed by the name of the filename of
the data file.  For example:

	BUILDSYS L631LIB6/DAT

would be the command used to build SYS6/CMD from the individual /CMD files if
using the supplied sample data.

WHAT TO DO NEXT
===============

The next thing to do would be to move your new custom library into position
on a system disk.  Note that it's highly recommended that you use a copy of
a system disk in drive :1 to write your new system library on, instead of the
system disk you're using in drive :0.  As you gain knowledge of how TRS/LS-DOS
works, you might be able to get away with it.  It all depends on what you've
done, of course.

The general syntax for replacing a /SYS file would be:

	Use ATTRIB to change the protection level of the /SYS file so you
	    can write to it.
	COPY sourcefile/ext:s SYSx/SYS.password:d (CLONE=N)

The (CLONE=N) parameter is *VERY* important.  Without it, the attributes of
the file you are copying will wipe out the SYSTEM attribute of the destination
file, which would not be good.

If we continue to use the sample for SYS6 on TRSDOS 6.3, the actual command 
would be the following:

	COPY SYS6/CMD SYS6/SYS.LSIDOS:1 (CLONE=N)

When finished, put the "new" operating system disk in drive :0 and try it out
by rebooting and using your modified commands.

If you're really ambitious, you could try replacing the commands in the table
stored in SYS1/SYS with new names.  The ID command is fairly useless, so it
would make a good candidate.  Just make sure you get the module ID and ISAM
number correct for your replacement command.  I had changed the ID command
to KILL (and duplicated the two bytes after "REMOVE") but since I'm so
used to typing the longer form, I wound up playing around with different
things instead.  The "LOG" utility makes a good built-in LIB command, for
example.

I hope this enhances your enjoyment of your TRS-80 Model 4.  I'm fairly sure
that the concepts in this program would work equally well for the Model 3
and LDOS 5.x.  Someday I'll get around to disassembling and commenting the
Model 1 and 3 versions of LDOS.

Pete Cervasio
(cervasio@airmail.net)

