ZCPR Version 3.4 Resident Command Package Source Code 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 RCPZRL10.LBR. Z34RCP10.LBR consists of the following files (uncompress with UNCR.COM): 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. Z34RCP10.DZC - This file. Z34RCP10.FOR - Short description of the library. Z34RCP10.HZP - Help file for the RCP, gives command syntax and examples. Z34RCP .LZB - Used to select features when assembling the RCP. Z34RCP10.NZW - Changes since Z33RCP02.LBR. Intended for former RCP users, this will be only of passing interest to new users. Z34RCP10.ZZ0 - Main file for assembling the RCP. 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 now, 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 "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, the RCP is loaded into memory from a file named SYS.RCP by the Z-System loader program, LDR.COM. Thereafter the RCP's commands remain active until the system is turned off or another RCP is loaded with LDR.COM. Using LDR.COM 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," LDR.COM provides 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 recently, 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 ZRLRCP10.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 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 two brand new utilities, NZCOM by Joe Wright and JetLDR by Bridger Mitchell, custom-assembling an RCP for a given target machine is no longer necessary. NZCOM and JetLDR 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, NZCOM and JetLDR 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 NZCOM and JetLDR. Using NZCOM or JetLDR, it is possible to load an RCP directly from RCPZRL10.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 or 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 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. At this writing NZCOM has just become available from Alpha Systems. JetLDR is under late beta testing and should become available to the general public soon. 5. Legal Use of These Files. Z34RCP is copyright 1988 by Alpha Systems. 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 Alpha Systems. 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 Alpha Systems 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. Alpha Systems may be reached at Alpha Systems Corporation 711 Chatsworth Place San Jose, California 95128 (408) 297-5594 Carson Wilson may be reached via Lillipute Z-Node Computer Bulletin Board System Chicago, 312-664-1730 300-1200-2400 Baud, 24 Hours