RomWBW/Source/BPBIOS/Z34RCP11/z34rcp11.doc

            ZCPR Version 3.4 Resident Command Package
                           Source Code

              Revised Documentation for Version 1.1
                 October 7, 1989 by Carson Wilson

                    Version 1.0 Documentation
                 June 17, 1988 by Carson Wilson


                            Contents
                            --------

               1.  Files in this Library.

               2.  Purpose of the Resident Command Package.

                    2.1.  "Resident" vs. "Transient" Commands.

                    2.2.  The Z-System Resident Command Package.

                         2.2.1.  Design Philosophy of the Z34 RCP.

               3.  Structure and Operation of the RCP Segment.

               4.  Generating an RCP for your System.

                    4.1.  The Z-Relocatable Approach.

                         4.1.1.  NZCOM and JetLDR.
                         4.1.2.  Z-Relocatable (ZRL) Code

                    4.2.  The Assembly Approach.

                         4.2.1.  Note on Assemblers.
                         4.2.2.  Assembly to Absolute Code.
                         4.2.3.  Assembly to Z-Relocatable Code.
                         4.2.4.  Adding Custom Commands to Z34RCP.

               5.  Legal Use of These Files.



1.  Files in this Library.

This library of files contains the assembler source code and 
accompanying documentation for the Z-System Resident Command 
Package (RCP).  To use Z34RCP you must be running ZCPR versions 
3.3 or above.  For pre-assembled Z-Relocatable (ZRL) RCPs, see 
RCPZRL11.LBR.  Z34RCP11.LBR consists of the following files 
(uncompress with UNCR.COM, QL.COM or LBRE.COM):

CLEDINST.CZM   - Installer for CLED command.
CLEDSAVE.CZM   - Command file utility for CLED.
RCPCLED .DZC   - Documentation on CLED.
RCPBASE .LZB   - Used to assemble an absolute address RCP.
RCPCMD  .LZB   - Used to include custom commands in the RCP.
RCP?????.LZB   - Code modules for the standard RCP commands. 
SYSDEF  .LZB   - Commonly used equates.
Z34CMN  .LZB   - Used to assemble Z-Relocatable RCP's.
Z34DEFN .LZB   - Offsets in the ZCPR 3.4 code.
Z34MAC  .LZB   - Assembler macros.
Z34RCP11.DZC   - This file.
Z34RCP11.FOR   - Short description of the library.
Z34RCP11.HZP   - Help file for the RCP, gives command syntax and 
                 examples.
Z34RCP  .LZB   - Used to select features when assembling the RCP.
Z34RCP11.NZW   - Changes since Z34RCP10.LBR.  Intended for former 
                 RCP users, this will be only of passing interest 
                 to new users.
Z34RCP11.ZZ0   - Main file for assembling the RCP.
ZSYSTEM .AZ    - General information about Z System.


2.  Purpose of the Resident Command Package.

     2.1.  "Resident" vs. "Transient" Commands.

Most of the commands used under CP/M and Z-System are "transient" 
commands.  The machine code for these commands (or "programs") is 
stored in "command files," whose file type is normally .COM.  
Thus, the machine code for WordStar is stored in a file called 
"WS.COM".

To run WordStar, the user issues the command "WS" at the command 
line, the operating system loads WS.COM from the disk drive to 
memory, and WS.COM takes over control of the computer.  If the 
user then exits WordStar and issues another command, the 
operating system can load another command file from the disk, 
reusing the area of memory previously occupied by WordStar.

Recycling memory in this way makes personal computers quite 
versatile, as the number of commands available to the user is 
only limited to the number of command files stored on disk.  
There are some drawbacks to this approach, however.  Although 
disk-based commands conserve memory by recycling it, they must be 
loaded from disk each time they operate.  This creates its own 
costs in terms of speed of execution, disk storage space, and 
memory reallocation.

The most obvious disadvantage of loading a file from disk each 
time a command is issued is that it takes time to find and load 
disk files.  Especially with floppy diskettes, the amount of time 
which elapses after the command is issued and before the command 
executes is significant.  A second drawback to disk-based 
commands is that commands will not execute unless their machine 
code is available on the disk system.  This means that the user 
must know what command files are available on disk before issuing 
commands.  The final disadvantage of disk file based commands is 
that some commands (e.g., SAVE) require that the area of memory 
normally overwritten by command files (known as the "Transient 
Program Area" or TPA) be preserved.

In answer to these difficulties, the creators of CP/M designed 
some of its commands as "built-in" commands.  The DIR, REN, SAVE, 
ERA, USER, and TYPE commands of CP/M 2.2 remain in memory and can 
be issued without loading machine code files from disk.  Thus, 
the DIR command provides a disk directory regardless of whether 
the command file "DIR.COM" is present on disk, and the SAVE 
command saves the contents of memory at 100 hex to a disk file.  
Residing permanently in memory, these commands are simple in 
order to leave memory for disk-based commands to load in.

     2.2.  The Z-System Resident Command Package. 

The creators of Z-System have followed the resident command 
philosophy of CP/M, extending and enhancing the capabilities of 
resident commands with the Z-System Resident Command Package.  
Under CP/M 2.2, resident commands are tightly integrated with the 
operating system.  The user is therefore limited to a fixed set 
of resident commands.  The code in the Z-System Resident Command 
Package is much more loosely linked with the operating system.

The RCP occupies a section of protected memory, but how that 
memory is used is only very loosely constrained.  The Z-System 
resident command package may be tailored for a wide variety of 
installations, and easily altered within a single installation.

          2.2.1.  Design Philosophy of the Z34 RCP.

Though any set of commands which will fit in the RCP memory area 
can be loaded as an RCP, a standard set of Z-System RCP commands 
have evolved over the years.  Distributed as the standard 
Z-System RCP, this set of commands consists of universal, 
single-purpose commands modeled after the resident command set of 
CP/M 2.2, such as DIR, REN, and ERA.

Keeping these commands simple both conserves memory and allows 
their use in custom command scripts.  None of the standard RCP 
commands require interaction on the part of the user--they 
perform a single function and quit.  Aliases or other command 
scripts which build complex commands from simple RCP commands 
therefore retain complete control over the user interface.

However, the standard RCP forms only one of many alternative uses 
to which the Z-System RCP memory segment may be put.  Since the 
RCP memory is protected, it can be used by background programs 
which continue to function even while other applications have 
been loaded into the transient program area.  Several such 
programs, including key-redefiners, screen-trapping programs, 
background numeric calculators, program assembly environments, 
and memory utilities have been developed.

Until Z34RCP, all but the most advanced users had to surrender 
their entire RCP to use the custom commands, even if the commands 
needed far less than the available RCP space.  Thus, to use a 
key-redefinition RCP, one was forced to give up all of his other 
RCP commands.  Z34RCP solves this problem by acting as a base to 
which programmers may easily add code.  By modifying the standard 
file RCPCMD.LIB, programmers can implement and distribute custom 
RCP commands which may be installed by those with only basic 
knowledge of assembly language.  See "Adding Custom Commands," 
below, for details.


3.  Structure and Operation of the RCP Segment.

Typically, the Resident Command Package occupies 2 kilobytes of 
memory, protected above the system's Basic Input Output System 
(BIOS).  Its internal structure is very simple, consisting of the 
five byte string "Z3RCP", a table of command names and their 
addresses within the RCP, and the machine code of the commands 
themselves.  This means that an RCP of a given length can contain 
any number of resident commands which will fit in 2k, from one 
large program to many shorter programs.

Further, since the RCP is independent of the rest of the 
operating system, the resident commands may be changed at will.  
On system startup, a default RCP is loaded into memory.  
Thereafter the RCP's commands remain active until the system is 
turned off or another RCP is loaded.

Using loader programs to load the RCP to memory allows another 
important ability--it can exchange RCPs during a single session.  
By allowing users to change their RCPs "on-the-fly," loader 
programs provide some of the benefits of transient commands even 
while preserving the benefits of resident commands.  In fact, 
even what portion of memory is allocated to the RCP can be 
altered in this way by advanced users! (see the Z-System User's 
Manual for more on this).


4.  Generating an RCP for your System.

Since Z80 computers come with a wide variety of operating system 
environments, it is impossible for a single segment of machine 
code function as a universal RCP.  Due to differences in 
operating system and hardware design, the size and location of 
memory available to the Z-System RCP vary widely.  Until 
Z34RCP, this meant that each type of Z80 computer required an RCP 
segment assembled specifically for that computer.

Now, however, there are two basic means by which you may generate 
an RCP for your system.  The simplest route is to load already- 
assembled Z-Relocatable code modules.  This technique is 
recommended for beginners and those with little experience in 
assembly language.  See RCPZRL11.LBR for pre-assembled RCP 
modules.  For more experienced users with an interest in 
customizing or their RCPs or adding their own commands, custom 
assembly of the files in this library is also an option.

     4.1.  The Z-Relocatable Approach.

          4.1.1.  NZCOM and JetLDR.

LDR.COM, the familiar Z-System segment loader first introduced by 
Rick Conn as a means of loading the various segments of the ZCPR 
environment from disk to memory, required that system segments be 
assembled to run only at system-specific addresses.  For example, 
if the system's RCP started at FA00 hex, only an RCP assembled to 
run at that starting address would function on the system.  
Therefore, separate SYS.RCP files were needed for each computer 
installation.

Thanks to several advanced loader utilities, namely NZCOM by Joe 
Wright and JetLDR and Z3PLUS by Bridger Mitchell, custom- 
assembling an RCP for a given target machine is no longer 
necessary.  These three programs can load specially assembled RCP 
segments (known as Z-ReLocatable or "ZRL" segments) to any area 
of memory.  Z-System users now need only obtain previously 
assembled RCP segments, much as they need only obtain assembled 
.COM or .OBJ files to run transient programs.

Using information in the system's environmental descriptor, 
advanced loaders load pre-assembled segments to the proper 
addresses in any system.  The only remaining constraint is the 
amount of memory allocated to the RCP.  While the standard RCP 
size is 2 kilobytes, many Z-System installations vary 
considerably from this standard, so it is still necessary to 
ensure that a ZRL segment does not exceed available RCP memory.  
Fortunately, this is taken care of automatically by the advanced 
loader programs.

Using NZCOM or JetLDR, it is possible to load an RCP directly 
from RCPZRL11.LBR.  See NZCOM or JetLDR documentation for full 
instructions on how to load Z-Relocatable RCPs with these 
programs.

          4.1.2.  Z-Relocatable (ZRL) Code    

The technique used by NZCOM and JetLDR to load a single RCP to 
any address in memory involves relocatable code.  Relocatable 
code has been used for years by the "linker" programs available 
to assembly language programmers.  Since only portions of a given 
Z80 machine code routine are specific to one memory address, it 
is possible to create "relocatable" files of Z80 routines (known 
by their file type .REL) containing all but the address-specific 
codes.  These files can then be very quickly relocated (or 
"linked") by a linker program to operate at any memory address.

Z-Relocatable code is simply a more sophisticated form of 
relocatable code.  ZRL files contain separately labeled segments, 
known as "named common blocks."  Where normal relocatable code is 
all linked to operate at one address at a time by the linker 
program, named common blocks allow the linker to distinguish 
between different sections of the file and to link each "block" 
to operate at a different address.

This represents a major step forwards in user convenience, and 
will certainly lead to more innovative work using the ZCPR system 
segments.  There is a minor drawback, however, inherent in the 
form of assembly required by NZCOM and JetLDR.  Before the advent 
of these two programs, system segments were equivalent to .COM 
files which were assembled to operate at addresses other than the 
standard 100 hex.  The ability to load a single system segment to 
any address depends partially on the form of the assembled system 
segment itself.

While public domain assemblers will produce absolute object 
files, more sophisticated assemblers, such as SLR's Z80ASM (a 
bargain at $50) are required to assemble code with named common 
addresses.  NZCOM and JetLDR thus greatly reduce the time needed 
by most users to install Z-System segments, but those wishing to 
assemble Z-Relocatable segments will probably need a commercial 
assembler.

     4.2.  The Assembly Approach.

Those with knowledge of assembly language may opt to assemble 
their own custom RCPs, including only the commands and options 
which match their exact requirements.  Z34RCP.LBR contains the 
complete source to the ZCPR 3.4 RCP.  The file Z34RCP.Z80 
contains include statements to combine the various library files 
during assembly.  The file Z34RCP.LIB contains all of the equates 
controlling assembly time options, and should be edited before 
assembling Z34RCP.Z80.

          4.2.1.  Note on Assemblers.

The development work on Z34RCP was done exclusively with the SLR 
Systems line of Z80 assemblers.  Hence, some of the source code 
is unavoidably specific to SLR and compatible assemblers.  Those 
using incompatible assemblers such as public-domain Z80 
assemblers should set the SLR equate in Z34RCP.LIB to FALSE.  
This removes most SLR-specific pseudo-ops, but some additional 
editing of the source files may be required for error-free 
assembly.  Unless your assembler can handle named common blocks, 
you will also want to set the ZRL equate in Z34RCP.LIB to FALSE.

          4.2.2.  Assembly to Absolute Code.

If you are assembling a custom RCP for use at one memory address 
only, or if your assembler can't handle named common blocks, you 
can set the ZRL equate in Z34RCP.LIB to FALSE, and instruct your 
assembler to produce absolute code (either a .HEX or a .COM file).

Before generating absolute code you must set addresses in the 
file RCPBASE.LIB for the particular installation.  Once you have 
set these addresses, you may proceed to assemble Z34RCP.Z80 to 
either Z34RCP.COM or Z34RCP.HEX.  If your assembler generated a 
.HEX file, use LOAD.COM to convert Z34RCP.HEX to Z34RCP.COM.

If you are running a version of ZCPR prior to 3.4, you must now 
alter two bytes in your Z-System environment segment to point to 
your system's CCP address.  The bytes at offset 39 and 40 hex 
(formerly containing "width of printer 2" and "lines on printer 
2") should contain a 2-byte address of your system's CCP, most 
significant byte last.

Z34RCP.COM may now be renamed to SYS.RCP and loaded with the Z- 
System loader program LDR.COM or Bridger Mitchell's JetLDR.

          4.2.3.  Assembly to Z-Relocatable Code.

Unlike absolute RCP segments, Z-Relocatable segments may be 
loaded to ANY address, provided enough RCP space to contain them 
is available.  To assemble a Z-Relocatable RCP, you will need an 
assembler which can handle named common blocks (see 4.2.1 above). 
Set the ZRL equate in Z34RCP.LIB to TRUE, and instruct your 
assembler to produce a relocatable (.REL) file.  The resulting 
Z34RCP.REL may then be renamed to Z34RCP.ZRL and loaded with 
NZCOM, Z3PLUS, JetLDR.

          4.2.4.  Adding Custom Commands to Z34RCP.

As mentioned above, I have designed Z34RCP as a base to which 
custom RCP commands may readily be added.  All code and command 
names for custom commands may be included in RCPCMD.LIB.  
Thereafter, whenever the RCP is assembled the commands added to 
RCPCMD.LIB will be included automatically.  To remove the custom 
commands, just replace the modified RCPCMD.LIB with an unmodified 
copy.  See RCPCMD.LIB for detailed instructions on how to add 
code and command names.

RCPCMD.LIB also facilitates distribution of custom commands to be 
included by others in their RCPs.  Simply distribute a copy of 
your modified RCPCMD.LIB along with instructions on how to use 
your custom commands.  Users may then easily include the new 
commands by substituting your modified RCPCMD.LIB for their 
original copy and reassembling their RCPs.

Of course, users of NZCOM, Z3PLUS, or JetLDR may simply trade 
custom RCPs in Z-Relocatable form and dispense with the need for 
any assembly work on the part of the user.  All three of these 
advanced loaders are available from Z Systems Associates (see 
below).


5.  Legal Use of These Files.

Z34RCP is copyright 1989 by Z Systems Associates (ZSA), all 
rights reserved.  Any commercial use of Z34RCP, defined as any 
situation where the duplicator recieves revenue by duplicating or 
distributing Z34RCP by itself or in conjunction with any hardware 
or software product, is expressly prohibited unless authorized in 
writing by ZSA.

Except for the file RCPCMD.LIB (see 4.2.4 above), you may 
redistribute Z34RCP.LBR in its present form only.  I encourage 
you to explore the source code, suggest improvements, and 
document errors.  However, please obtain permission from Z 
Systems Associates before redistributing any of these files in 
altered form.  This will prevent confusion by allowing your work 
to be coordinated with the efforts of others.

The Z Systems Associates are:

 Sage Microsystems East
 Selling & Supporting the Best in 8-Bit Software
 1435 Centre St., Newton Centre, MA 02159-2469
 Voice: 617/965-3552 (9:00am - 11:30pm)
 Modem: 617/965-7259 (password = DDT)(MABOS on PC-Pursuit)

and:

 Plu*Perfect Systems
 "==World-Class Software"
 410 23rd Street, Santa Monica, CA 90402
 Voice: 213/393-6105 (evenings)
 Modem: 213/670-9465 (leave message for "Bridger Mitchell")

For more information on Z System, check at the above bulletin 
board systems, or consult The Computer Journal for excellent 
articles on ZCPR and CP/M.  The Computer Journal is published six 
times a year by Publishing Consultants, 190 Sullivan Crossroad, 
Columbia Falls, MT 59912, phone 406/257-9119.  An issue averages 
forty pages with few ads.  Subscription rates are $16 for one 
year (6 issues), or $28 for two years (12 issues) in the U.S., 
$22 for one year Canada and Mexico, and $24 (surface) for one 
year in other countries.


Carson Wilson is the operator of:

              Antelope Freeway Remote Access System
                      Chicago, 312-764-5162
                  300-1200-2400 Baud, 24 Hours