Thanking Dreas Nielsen for his letter reminds me that Art Carlson and I
would like very much to start up a Z-Letters feature in TCJ, a kind of
letters-to-the-editor section specializing in Z-System questions, comments,
discussion, and ideas. I am willing to handle answering or otherwise
responding to those letters, but I will depend on you readers to send them
in. And rest assured that we are not looking only for letters like Dreas's
containing brilliant suggestions. A good set of simpleminded questions
would be quite well appreciated, thank you. They would help us a great deal
in learning what aspects of Z-System are confusing to users so that we can
try to clarify them.
New ZSIG Releases
-----------------
We have quite a few excellent new programs to release on ZSIG diskettes
this month. I have not yet finalized exactly what will be included on
release diskettes #2 and #3, but I don't want to pass up this opportunity to
publicize them.
First of all, I am very happy to report that all the programs I
proposed two issues back have now been written, and I will describe them
first.
FCP10.LBR
This is the new flow control package (FCP) that I wrote with
valuable assistance from Howard Goldstein (New Haven, CT). This program was
described in some detail in the last column, so I will not say too much
about it here. The two most important innovations are 1) the addition of
AND and OR commands and 2) the FCP's ability to load and run IF.COM in high
memory where it will not interfere with data in the beginning of the
transient program area at 100H.
COMIF10.LBR
This is the companion transient IF processor that is intended to
replace IF.COM. Also described last time, it offers an enormous number of
new test conditions and syntax forms. This one was also written by me
together with Howard Goldstein.
SETPATH1.LBR
This is an extended version of the original PATH command. It allows
one optionally to add and remove path elements from the beginning or the end
of the existing path. The path display is also improved. Robert Demrow, a
fellow member of the Boston Computer Society CP/M Group wrote this one.è
EDITND.LBR
Al Hawley (Z-Node #3 in Los Angeles) really went all out with tools
to work with the named directory register (NDR). EDITND lets one edit the
names directly in the NDR. Names and/or passwords can be added, deleted,
and changed.
SAVNDR.LBR
After you've edited the NDR, this program lets you save the results
to an NDR file. Again by Al Hawley.
LOADND12.LBR
The last in the Hawley set, this program can automatically update
the names in the NDR using either the special file name system in LDSK or by
loading an NDR file whose names are applied to the current floppy disk only.
The next ZSIG release will also include the following programs.
ZPATCH11.LBR
This is another masterpiece from Steve Cohen (Chicago, author of
'W', the wildcard shell, on the first ZSIG diskette). It is by far the best
file patcher I have ever seen -- a real joy to use. Steve sure is clever
when it comes to shells! Who would have thought to make a file patcher into
a shell? But this way one can run a command from inside ZPATCH and then
return to one's exact place to continue working. The 'X' command in ZPATCH
automatically runs the file one is currently patching (provided it is a COM
file) so that one can see the effect of the changes. Marvelous!
MEX2Z.LBR
This is yet another brainstorm of NAOG chief Bruce Morgen (who has
quite a stormy brain). MEX2Z and my adaptation of it for MEX-Plus, MEX+2Z,
give the MEX communication programs the ability to 'shell', that is, to run
a Z-System command apparently from within MEX. For example, if you enter
the MEX command line "CPM;CRUNCH FN.FT", you will exit from MEX, the file
will be crunched, and then you go right back into MEX. This is especially
handy when you are trying to debug a MEX script. Bruce picked up on the
very clever trick introduced by Ted Emigh in FINDERR, namely, running a
program that examines information left behind in memory by the program that
ran before it. In this case it is the MEX command line buffer that is
picked up. Even if you don't use MEX, it is worth looking at these programs
just for their educational value.
FF10.LBR
I finally decided to do something about the shortcomings of FINDF,
the utility for determining where files are located in your system. FF hasèa 16-bit configuration word that can be patched (roll out ZPATCH!) to define
which drives should be searched by default (this is particularly useful when
your constellation of drives has a hole in it, such as A, B, C, and F). You
can override the default drive list by specifying a set of drives to scan on
the command line. A whole list of file specifications can be given, and
each one is automatically wildcarded, saving the user a lot of typing. If
you want to find all programs starting with "SD", just enter "FF SD". The
"SD" turns into "SD*.*" automatically. Similarly, "FF .LBR" will find all
library files. "FF SD,.LBR" will find both.
PPIP15.LBR
This is the next step in the evolution of PPIP (PPIP14 is on ZSIG
diskette #1). The main addition is support for DateStamper time and date
stamping. Having fallen in love with DateStamper, I just had to have some
file copying tools that would preserve the time and date information, so I
added that capability to PPIP and to ZFILER.
ERRSET11.LBR
This little tool lets you either display the current or directly
enter a new error handler command line. Strictly speaking, error handling
in ZCPR3 is not performed by loading an error handling program but by
executing an error handling command line. This command line is stored in a
16-byte string in the message buffer. When an error handler is installed by
invoking its name manually from the command line, it writes only its name
alone into that buffer. ERRSET lets you enter a complete error command
line, such as A15:VERROR. By including an explicit DU: or DIR: form, the
error handler will be found and loaded faster. On the other hand, ERRSET
will let you enter the name of a nonexistent error handler, so watch out.
Power has its price. Written by yours truly.
Customizing Z-COM
-----------------
We now turn to the piece-de-resistance for this article -- a discussion
of techniques for customizing Echelon's automatically installing Z-System
package known as Z-COM. This will be the first of a two-part series. This
time I will cover the more elementary aspects of the subject, those
modifications that can be made by changing only data structures in the Z-COM
files. Next time I will delve into customization techniques that involve
serious hacking (such as modifying the Z-COM code itself).
I will begin with an overview of what Z-COM is, the philosophy behind
it, the procedure for installing it on a particular computer, and how one
uses it to create a Z-System automatically. Then I will give an elementary
discussion of how it works and the structure of the COM file that magically
transforms one's ordinary CP/M machine into a 'Z' machine. Next I will show
you how to make some simple patches that eliminate the initialization
operations that are performed by the startup file and make Z-COM come upèready to go instantly. This includes setting the wheel byte, defining the
symbolic command search path, putting in the terminal capability descriptor
(TCAP) for the user's terminal, installing the user's named directories,
installing an external error handler, and even setting up an initial shell.
With those techniques mastered, we can then go on to make changes to
the system modules. The simplest of these is replacing the standard ZRDOS
that comes with Z-COM with the latest-and-greatest Public-ZRDOS-Plus version
1.7. Slightly more complex is the replacement of the environment
descriptor (ENV) and the two command modules: the RCP (resident command
package) and the FCP (flow control package). For these changes we have to
edit some configuration files, assemble new code modules, and install the
new modules into the Z-COM file. By this point you will be ready to
generate and install a new version of the ZCPR3 command processor, an
operation that requires one important extra step (a simple one, but one that
must not be overlooked).
Why Z-COM
Consider this situation. The Z-System is a wonderful replacement for
CP/M, one that greatly enhances the utility and ease of operation of an 8-
bit Z80-compatible computer. I can't understand why anyone would not enjoy
and benefit from its features and capabilities. However, installing it in
the conventional fashion required changing the BIOS (Basic Input Output
System), the hardware-dependent part of the operating system. Unfortunately,
many (actually most) manufacturers consider their BIOS to be proprietary (or
embarrassingly poorly written), and they refuse to release the source code.
And even if they do make it available, perhaps for an extra fee, what if you
do not know how to make the required changes to support the ZCPR3 command
processor? Well, enter Z-COM.
Z-COM was the brilliant conception of Joe Wright, the nation's
preeminent BIOS writer (author of the BIOSes for the Ampro Little Board,
Micromint SB180, and the soon-to-be-available ON! computer from Oneac). With
Z-COM one does not need the BIOS source code because there are no changes to
make in it. One doesn't even need MOVCPM. Z-COM runs on almost any
standard CP/M 2.2 system, converting it in situ to a Z-System. There are a
few CP/M 2.2 computers on which Z-COM will not work (usually because at
least some part of their memory space operates in a funny way), but the
great majority will. For those of you with CP/M version 3 (aka CP/M-Plus --
a real misnomer in my opinion), I'm afraid you are out of luck. CP/M 3 is
fundamentally different from CP/M 2.2, and no one has yet been able to
concoct magic powerful enough to transform it into a Z-System.
I hope my discussion here will inspire some of you to purchase Z-COM.
If it does, then see the ads in TCJ by Sage Microsystems East and Echelon
for more information. I personally think that a modified Z-COM is the best
way to implement Z-System, because, as we will see by the end of this series
of articles, it gives one far greater flexibility than with a manually
installed system.è
Installing Z-COM
Here is a brief description of how one gets Z-COM running on one's
system. The standard procedure goes like this. Take a freshly formatted
disk, 'sysgen' the CP/M 2.2 operating system to it, copy onto it all the
files on the Z-COM release disk, put this disk into drive A, and reboot the
system either with the reset button or by entering control-c. Now enter the
command "SUB ZCCOM". This starts a batch operation, and you can now sit
back, relax, and watch your computer do all the work. Toward the end of the
process, which takes a couple of minutes, a program called TCSELECT will run
and ask you to choose your terminal from a large menu. The result will be a
file called MYTERM.Z3T containing information about your terminal that
permits Z-System programs to perform screen operations without installation.
What's Going On During Installation
In the first part of the installation process, the Z-COM system
creation program ZCLD.COM determines the memory address at which your BIOS
operates and generates a corresponding Z-System. To do this, it reads in a
number of special relocatable files (most with file type SPR, which stands
for system page relocatable) and produces four new files: ZC.COM, ZCX.COM,
ZC.ENV, and ZC.CP. The first file, whose operation we will describe in
detail below, is the one that transforms the vanilla CP/M system to the
amaretto-double-chocolate almond Z-System with jimmies (if you don't know
what jimmies are, ask someone from Boston).
The second file, ZCX.COM, is a program that transforms you back. Why,
you ask, would one ever go back to vanilla after experiencing the ecstasy of
amaretto-double-chocolate-almond? Well, Z-System does have one significant
drawback. You don't get all those great features for free. They cost a
considerable chunk of TPA (transient program area) -- 5.5K in the case of Z-
COM (though we will see next time how to reduce this if you are willing to
forego some of the features). The smaller TPA has almost never caused any
problem with the programs I use, but some people do have problems, and it is
nice to know that a simple "ZCX" command will bring back the old CP/M with
its full-sized TPA. Next time I will explain how we can even change to a
different Z-COM system with a larger TPA.
The third file, ZC.ENV, is the environment descriptor file for the
system that ZCLD created. It is automatically included in ZC.COM, so it
does not have to be loaded using LDR, but it is used by Z3INS to install the
environment information into the utilities.
The last file, ZC.CP, does not even appear in a directory listing; it
is hidden up in user area 15, out of harm's way. The user is not normally
concerned with this file, though if you want to create another Z-COM system
disk, you have to remember to copy it, as well as the others mentionedèabove, to the new diskette. We will discuss its purpose later.
How ZC.COM Works
As we said above, ZC.COM is the program that transforms your mundane
CP/M system into an exciting and powerful Z-System. How does it do it?
Several simple principles are involved.
ZC.COM is basically a loader program. The file itself consists of two
parts. The first page of code (100H to 1FFH) is the loader code. The
second part (200H to 2DFFH) is the memory image of a Z-System that is copied
into place by the loader. The process is like the 'big bang' theory of
creation -- the whole Z-System just appears complete in one operation!
The memory map of the ZCOM-System generated for my BigBoard I computer,
on which I performed these experiments, is shown in Fig. 2. Its real CP/M
BIOS is at E800H. The Z-System addresses were determined by running the
utility SHOW.COM after Z-COM was loaded. The corresponding addresses in the
ZC.COM file were obtained by inspecting it with a debugger. Once a few
addresses (like the RCP and FCP, which have obvious headers), were
determined, the rest was obvious. The ZC.COM system image is at a constant
offset from the real system. In this example, that offset is BA00H. If Z-
COM is installed on a different system, the real system addresses and the
offset value will be different, but the addresses of the system segments in
the ZC.COM image will be the same. In general, the offset between the
corresponding addresses will be 2E00H less that the address of the native
A0:SYS>save 2dh zcnew.com ; Save new version of ZC
If you have a shell running while this process is being carried out, you
have to include the SAVE command on the same line as the DDTZ command, since
when the shell loads it wipes out the memory image in the TPA. By putting
the SAVE command on the same line, it is run before the shell is reloaded.
I have used the above technique and found it to work very nicely, but a
word of caution is in order. A purist would copy the memory areas only for
the specific segments to be modified. The external file control block and
the parts of the message buffer other than the byte at offset 0 (D580, where
the error-handler-flag is kept) and bytes at offsets 10H to 1FH (D590-D59F,
where the error handler command line is kept) would not be copied. Copyingèthe entire message buffer works as described above, but if you try to make a
ZEX batch file to do this, you will get into trouble, since ZCNEW.COM will
then contain an image of the message buffer with the ZEX-running flag set.
To test ZCNEW, make a new STRT.COM alias that just echoes a signon
message (first rename the old one in case you want it back later), run ZCX
to exit from Z-COM, and then run ZCNEW. Your own personalized Z-System
should pop (almost) instantly to life. After determining that it is really
working correctly, you can rename ZCNEW.COM to ZC.COM. Again, I recommend
keeping old versions with names like ZC1.COM, ZC2.COM, and so on, on an
archive disk.
Putting in a New DOS
Now let's make a change that could not be accomplished using utility
programs, as all of the above changes could be. Let's replace the older,
non-public version of ZRDOS that comes with Z-COM with the latest version
1.7 of Public-ZRDOS-Plus. The first part of the process is same as that in
a manually installed Z-System. One takes the ZRDOS generating program
ZRDINS17.COM, installs it using Z3INS, and runs it. Having been installed,
it will automatically know the three facts it needs: where the DOS, ENV, and
wheel byte are located. After it finishes running, there will be a binary
image file called ZRDOS17.BIN.
With a manually installed Z-System we would now have to go through a
somewhat complex process involving 'sysgening' a system image from the
system tracks, patching in the new DOS using a debugger, and 'sysgening' the
image back onto the system tracks. With Z-COM things are actually
considerably easier, since the two 'sysgening' steps can be skipped. Here
is the command sequence:
A0:SYS>ddtz zc.com ; Run debugger and load ZC.COM
-izrdos17.bin ; Initialize the file control block
-r900 ; Read with offset 900h so that the object
; ..file will load at A00h
-g0 ; Warm boot out of debugger
A0:SYS>save 2dh zcnew.com ; Save new version
As before, exit from Z-System with the ZCX command (or just hit the reset
button if that is more convenient). Then load the new system and run the
DOSVER utility. Voila! There is version 1.7.
Now let me show you a trick that makes patching even easier and doesn't
require a debugger at all. Just use the following command sequence:
A0:SYS>get 100 zc.com ; Load ZC.COM at address 100H
A0:SYS>get a00 zrdos17.bin ; Load ZRDOS17.BIN at address A00H
A0:SYS>save 2dh zcnew.com ; Save the new memory image
With this technique there is no computing of offsets, and it uses only ZCPR3èbuilt-in commands (GET and SAVE). The one thing you have to remember is
that the GET command loads entire files, and so this technique can only be
used to patch in things that come in contiguous blocks with a length that is
an integral multiple of 128 bytes. If you look at the memory table of
ZC.COM, however, you will see that this includes all system modules that
ever exist in the form of files: the CPR, DOS, NDR, ENV, TCAP, RCP, FCP, and
IOP. These patches can be done very nicely from alias scripts. For
example, since one might often change one's named directories, the following
alias might be handy:
alias PUTNDR:
IF NULL $1
ECHO SYNTAX: $0 NDR-FILE-NAME
ELSE
ERA ZCNEW.COM
GET 100 ZC.COM
GET 1A00 $1.NDR
SAVE 1DH ZCNEW.COM
ECHO TEST ZCNEW.COM
FI
Similar aliases could be used for replacing other modules such as RCPs and
FCPs.
New Command and System Modules
Speaking of RCPs and FCPs, let's talk a little about how we generate
new versions of these and other system modules. There is no need to discuss
the patching techniques. They are the same as what we have already seen.
The question is: how do we generate the new SYS.RCP, SYS.FCP, and SYS.ENV
modules?
The procedure is the same as in a manual install system, except that in
a manual install system we already had the necessary Z3BASE.LIB file that is
required for the assembly of new system modules. So far we have not needed
one with Z-COM. To make things easier, Joe Wright has kindly provided us
with a generalized Z3BASE.LIB file. All we have to do to adapt it to our
system is to use an editor to fill in the address of the environment
descriptor in the "Z3ENV SET ..." definition near the top of the file. One
further hint: while you are at it, change the SET to an EQU. If you use
Z3BASE.LIB to assemble a file in Zilog mnemonics, the assembler will not
accept SET, since that is a Zilog opcode. You would have to change it to
ASET in that case, but there is no reason not to use the universal EQU. Some
programs also require definitions for YES and NO, so you might want to add
the lines:
YES EQU TRUE
NO EQU FALSE
èOne last addition. The RCP, FCP, and ENV modules do not need it, but other
files, and most notably the command processor code, require an equate to
define the address of the entry point to the command processor. This is a
part of the normal Z3BASE file, but Joe Wright forgot to put it in.
Someplace after the Z3ENV equate, add the line:
CCP EQU Z3ENV - 1A00H
Now you should be all set to assemble up new system modules, like the new
FCP10 from ZSIG. You might also want to assemble a customized SYS.ENV with
the correct values of maxdrive and maxuser and your own choice of printer
and console definitions (see "ZCPR3, The Manual" for details).
"ZCPR3, The Manual" explains in detail how to carry out the assemblies,
though I find that the discussion there makes the process look more
complicated than it really is. Basically, you assemble the module to a HEX
file, convert the HEX file to a COM file using MLOAD, and then rename the
COM file to the proper name for the module (e.g., "REN SYS.FCP=FCP10.COM).
If you have the SLR assemblers, you can assemble the module directly to a
COM in a single pass and skip the MLOAD step. Finally you test the module
by loading it using LDR.
Replacing the Command Processor
Replacing the command processor is no more difficult than changing any
of the other modules in the system. In fact, as we will soon see, it is
much easier to test a new CPR with Z-COM than it is with the manually
installed Z-System.
The basic procedure is as we described for the RCP or FCP. As usual,
edit the configuration LIB file (Z3HDR.LIB or Z31HDR.LIB if you are using my
experimental version ZCPR315D) and assemble the code. One additional hint.
Again, if you have the fabulous SLR Systems assemblers SLRMAC, Z80ASM, or
SLR180, select the option to assemble directly to a COM file, not to a HEX
file. It is a shame that so many books and articles have taught the
unnecessarily complex patching method based on HEX files with their
extremely tricky offset calculation. It is much easier to work with a COM
file where the load offset in the debugger is quite straightforward, namely,
100H below where you want the file to go, no matter what address it was
assembled for. If you are using an assembler that can produce only a HEX
file, then use the public-domain MLOAD to convert it to a COM file just as
was done to make the RCP and FCP files.
Now that you have ZCPR3.COM or some such file, all you have to do is
substitute it for the file ZC.CP in A15:. It would be a sign of foolhardy
optimism to destroy the original ZC.CP. I would recommend renaming it to
something like ZCOLD.CP and then copying the new one into place with a
command like "PPIP A15:ZC.CP=ZCPR3.COM". Now just hit control-c to warm
boot, and the new CPR will be running!
è If things did not work out as you intended (and especially if the new
CPR just crashed the system), you can reboot and reload ZC.COM. Remember,
you did not change the CPR image in ZC.COM yet, and things will be fine so
long as you don't warm boot. Before that happens, you should rename
ZCOLD.CP back to ZC.CP. Then you can try again. That is sure a lot easier
than all the 'sysgening' required to test a new CPR with the manually
installed Z-System.
If all went well, the system is now running just the way you hoped it
would. Once you've tested it and are satisfied that it really is working
correctly, you can patch the new CPR into ZC.COM so that it will be ready
immediately after Z-COM loads. The following commands will do it:
A0:SYS>get 100 zc.com
A0:SYS>get 200 a15:zc.cp
A0:SYS>save 2dh zcnew.com
As usual, once you have verified that ZCNEW is working, rename it to ZC.COM.
Summary and Plans
-----------------
That wraps things up for this time. You now know how to make enough
patches to mold a Z-COM system pretty well to your own tastes. If you have
Z-COM, I hope you will experiment some before the next column appears. In
that column we will really dig into Z-COM and do some wild things. If you
have any suggestions or questions, please send them along. My address and
phone numbers are listed below.
As a little reward for those of you who plowed through this whole piece
(or who were taught the trick I was as a freshman in college to read the end
of a paper or essay before you start at the beginning), here is a little
tidbit. ZCPR version 3.3 is coming very soon. I already have a nearly
complete version of it patched into the Z-COM I worked up for this article.
I expect that Z33 will have been released or will be very close to release
by the time this column appears, and I will devote some space to a
discussion of its new features in the next column.
Jay Sage
1435 Centre Street
Newton Centre, MA 02159
voice: 617-965-3552
modem: 617-965-7259
[This article was originally published in issue 28 of The Computer Journal,
P.O. Box 12, South Plainfield, NJ 07080-0012 and is reproduced with the
permission of the author and the publisher. Further reproduction for non-
commercial purposes is authorized. This copyright notice must be retained.
(c) Copyright 1987, 1991 Socrates Press and respective authors]
