Documentation on CCPZ - A Z80 Version of the CP/M CCP CCPZ is a Group Project By RLC, FJW, KBP, RGF, RJM, SBB CCPZ Documentation By RLC Table of Contents ----- -- -------- Introduction 2 Part A: Installation Instructions 4 CCPZ Integration Example 5 Setting the CCPZ Inline Options 8 REL, BASE, CCPLOC, RAS 8 Customization Symbols 8 NLINES, WIDE, PGDFLT 8 PGDFLG, MAXUSR, SYSFLG, SOFLG, SUPRES, DEFUSR, SPRMPT, CPRMPT, NUMBASE, 9 SECTFLG, FENCE 10 Part B: Usage Instructions and Explanation of Commands 11 The CCPZ Command Hierarchy Search 11 The CCPZ-Resident Commands 13 DIR, ERA 13 LIST, TYPE, SAVE, REN 14 USER, DFU, JUMP, GO 15 GET 16 CCPZ Error Messages 17 Documentation on CCPZ - A Z80 Version of the CP/M CCP CCPZ is basically a rewrite of the CP/M Console Command Processor (CCP) which is designed to run as part of CP/M on Z80- based microcomputers. In most cases it is upward-compatable with the original CP/M Version 2.2 CCP. CCPZ, however, provides many extensions to the CP/M CCP. Among these are: . The TYPE function can be made to page or not page its output at the user's discretion . A LIST function is available which sends its output to the CP/M LST: Device and does NOT page . The DIR command has been extended to allow the dis play of the system files or all files . The ERA command now prints out the names of the files it is erasing . The current user number may be included as part of the command prompt; if the user is under a number other than 0, the prompt is of the form 'du>' (like 'A2>' or 'B10>'), and, if the user is under 0, the prompt may be 'd>' or 'd0>' as per his choice . The SUBMIT facility has been changed in two basic ways: - the prompt changes to 'du$' or 'd$' when the SUBMIT command is printed - the $$$.SUB is executed from the currently log ged-in disk (NOT just from A:) . A command-search hierarchy is now implemented which is executed roughly as follows: - the user's command is checked against the CCP- resident commands and executed immediately if a match is found - failing that, the current user number on the current disk is scanned for the COM file; the COM file is loaded and executed if found - failing that, a default user number (initially 0 but can be reset with the DFU CCP-resident command) on the current disk is scanned for the COM file; the COM file is loaded and executed if found - finally, failing that, the default user number on disk A: is scanned for the COM file; the COM file is loaded and executed if found or an error message (COMMAND?, when COMMAND was the user's command name) is printed . The numeric argument for the SAVE command can be specified in hexadecimal so that the user may employ the values presented by tools such as DDT exactly as they are given . A GET command which loads a file at a specified memory address and a JUMP command which "calls" the subroutine at a specified memory address have been added; a GO command which "calls" the subroutine at 100H (subset of the JUMP capability) has also been added This document provides the user of CCPZ with the following information: Part A: Installation Instructions Part B: Usage Instructions and Explanation of Commands -- Part A Installation Instructions In order to install CCPZ on a target microcomputer (must be currently running CP/M 2.2), the user must know two basic things: 1) Where his CCP is currently running in memory 2) Where his CCP is located in the SYSGEN image, or, for systems which don't support SYSGEN (such as P&T CP/M 2.2 for the TRS-80 Model II), where his CCP is located on disk and how to place the new CCPZ on top of it The first question is answered relatively easily. A pro gram, known as either BDOSLOC or BDLOC (for BDOS Locator), is provided with CCPZ. You should assemble this program for your particular computer (change the base ORG if you are running non- ORG-0 CP/M) and execute it. Upon execution, it will provide you with the base address of (1) the BDOS and (2) the CCP for your particular system. BDOSLOC has worked correctly for all systems tested so far, but there is always a chance that it may NOT work for some non-tested system. For the time being, assume that it works correctly and record the starting base page address of your CCP. The second question is answered not nearly so easily. If you have the ability to SYSGEN your system, it is much easier (commonly) than if you do not. You must, after assembling the CCPZ properly, integrate it into the sysgen (or disk) image of CP/M. This can be done by obtaining a SYSGEN image of your system, scanning it via a debugger such as DDT to find the offset for the CCP, reading the new CCP in on top of the old one, and finally running SYSGEN again to place the resultant system on disk. If you DO NOT have SYSGEN capability, a Disk Utility program is required to locate the CCP on disk and then write the new CCPZ on top of the old one. The net result of this integration is the placement of the new CCPZ onto disk in the proper place so that it will be loaded with the rest of CP/M on cold boot and executed properly. To find the original CCP, you typically have to locate it by its appearance. It is probably stored contiguously on disk, so, once it is found, a sequential overwrite is all that is required. Probability is extremely high that it is stored contiguously in the SYSGEN image. The CCP starts with two (2) and ONLY TWO jump instructions followed by a buffer area (possibly containing an initial command and/or the Digital Research copyright notice). The Digital Research manuals show the CCP to reside at address 980H in the SYSGEN image, but this may vary with system. To find this image, use DDT or some other such debugger, load the SYSGEN image you can get via SYSGEN, and examine memory starting at around 900H for the two (and ONLY two) jumps described above. If you find an area with more than two jumps (a group of them), you are probably looking at the BIOS and should go lower for the CCP. The CCP will probably start on an even page or half-page address (like 900H, 980H, 1100H, etc). Now that the location of the CCP has been found, record this address for later. You are now ready for the integration of CCPZ into your system. To do this, perform the following steps using the information of the page address of the CCP (obtained from BDOSLOC and called CCPLOC within CCPZ) and the SYSGEN image address of the CCP (called IMAGE for reference in this document). 1. Edit CCPZ and set the CCPLOC equate to the value obtained from above. Also set any flags and values as you desire (see the section on "CCPZ Customization" below). When satisfied, end the edit session. 2. Assemble CCPZ with MAC (or equivalent). This assembler is required because of the MACROs used. Only the resultant HEX file is required. 3. Assuming that you can use SYSGEN, obtain a SYSGEN image of your current CP/M system and save it on disk. 4. Load the SYSGEN image into memory with DDT (or equivalent). Once loaded, verify that the original CCP is at the IMAGE address found above and compute the integration offset using the DDT H command: H, The second number displayed gives you the OFFSET value required for step 5. 5. Integrate CCPZ into your SYSGEN image via DDT's I and ROFFSET commands. Use ICCPZ.HEX (or the name of your version of CCPZ) to load the FCB and ROFFSET (where OFFSET was computed in step 4) to load the CCPZ.HEX file into memory at the proper location. Check to see that CCPZ is indeed properly loaded by examining the SYSGEN IMAGE area. 6. Place the new system on disk by running SYSGEN and NOT loading the system from disk (use the memory image). For further clarification of the above process, the following is a sample terminal session which outlines the steps taken. CCPZ Integration Example B>; Sample terminal session for integrating CCPZ B>sysgen SYSGEN VER 2.2 SOURCE DRIVE NAME (OR RETURN TO SKIP)b SOURCE ON B, THEN TYPE RETURN FUNCTION COMPLETE DESTINATION DRIVE NAME (OR RETURN TO REBOOT) B>save 34 cpm56.com <-- We now have a SYSGEN image of CP/M to work with B>xdir XDIR Version 2.6 User Number: 0, Double Density File Attributes: Non-System Filename.Typ Size K RS Filename.Typ Size K RS Filename.Typ Size K RS -------- --- ------ -- -------- --- ------ -- -------- --- ------ -- !TEXTWRK.-12 0 R CCP .DOC 8 EE687 .TXT 4 CCPV24 .AQM 34 TFS .HLP 6 R EE687PRE.TXT 4 CCPV24 .ASM 50 CONTENTS.T01 6 SW1 .TXT 10 CCP .BAK 4 CONTENTS.T02 4 SW2 .TXT 2 CPM56 .COM 12 CONTENTS.T03 4 B: 30 Entries & 22 Files -- 338K Bytes Remaining File Data: 14 Files -- 154K Bytes Displayed B>bdosloc <-- Now to locate the CCP's address The Base Page Address of this system's BDOS is C5 The Base Page Address of this system's CCP is BD <-- This is it B>ddt cpm56.com <-- Now to find the CCP in the SYSGEN image DDT VERS 2.0 NEXT PC 2D00 0100 -d900,90f <-- Start looking around here 0900 31 80 E7 3E 06 3C 3C FE 1B CA 00 C2 DA 11 E7 D6 1..>.<<......... -da00,a0f 0A00 31 00 01 01 01 0C C5 CD 0F E4 21 00 BE 11 00 04 1.........!..... -db00,b0f 0B00 31 00 01 01 01 11 C5 CD 0F E4 21 00 C0 11 00 02 1.........!..... -db80,b8f 0B80 31 00 01 01 09 01 CD A8 00 21 00 D2 11 00 C2 0E 1........!...... -- Detail Left Out -- -d1100 <-- I found it at 1100H; note the 2 JMP's 1100 C3 FF BD C3 FB BD 50 10 20 20 20 20 20 20 20 20 ......P. 1110 20 20 20 20 20 20 20 20 00 00 00 00 00 00 00 00 ........ 1120 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................ -- Detail Left Out -- -^C <-- Return to CP/M; I know that CCPLOC will be BD00H and the IMAGE offset is 1100H B>ed ccpv24.asm {edit CCPZ here and place CCPLOC=BD00H}# -- Detail Left Out -- B>mac ccpv24 $pz sz <-- Now to assemble the CCP CP/M MACRO ASSEM 2.0 C4FF <-- Note that CCP MUST end before BDOS begins! 014H USE FACTOR END OF ASSEMBLY B>ddt cpm56.com <-- Now to integrate! DDT VERS 2.0 NEXT PC 2D00 0100 -h1100,bd00 <-- Compute offset for new CCP CE00 5400 <-- Offset is 5400H -iccpv24.hex <-- Init FCB -r5400 <-- Read in new CCP with offset NEXT PC 2D00 0000 -^C <-- Done! B>sysgen <-- Now to SYSGEN onto disk SYSGEN VER 2.2 SOURCE DRIVE NAME (OR RETURN TO SKIP) <-- Use memory image DESTINATION DRIVE NAME (OR RETURN TO REBOOT)b <-- onto B: DESTINATION ON B, THEN TYPE RETURN FUNCTION COMPLETE DESTINATION DRIVE NAME (OR RETURN TO REBOOT) <-- Done for now B> -- Setting the CCPZ Inline Options The following are the four basic options available to the user under CCPZ for customization of his package. Option Name Function REL Configures CCPLOC (CCPLOC equ 0) for integration via MOVCPM rather than the DDT/SYSGEN technique outlined above; set to TRUE for MOVCPM integra- tion or FALSE for DDT/SYSGEN integration BASE Base address of your CP/M system; standard CP/M has a base of 0, but some CP/M systems (such as for the TRS-80 Model I and Heath/Zenith H89/Z89) start physical RAM memory at a higher address; equate BASE to the starting RAM memory address of your system CCPLOC This is the starting address of CCPZ; set the second CCPLOC equate to the address you obtain from BDOSLOC RAS This is an equate which masks out selected CCPZ command functions for security purposes on Remote Access Systems such as Bulletin Boards; the masked out functions currently include SAVE, ERA, REN, JUMP, GO, and GET; set RAS to TRUE to mask these out or FALSE to leave them in Customization Symbols The following symbols are provided for further customization of CCPZ to a user's particular tastes and hardware facilities. Option Name Function NLINES Number of lines on the user's CRT for paging WIDE This equate is used to select a narrow or wide display under the DIR command; if WIDE is equated to TRUE, each file name is separated by two spaces, a FENCE, and two more spaces; if WIDE is equated to FALSE, each file name is separated by one space, a FENCE, and one more space PGDFLT This is the Paging Default flag for the TYPE command; if PGDFLT is set to TRUE, the TYPE command will page its output by default and the P option on the TYPE command (see below) will prohibit paging; if PGDFLT is set to FALSE, the TYPE command will NOT page its output by default and the P option will enable paging PGDFLG This sets the option character in the command line for the TYPE command (the 'P' mentioned above); if the user wishes to change this option character, he need only change this equate MAXUSR This is the largest user number recognized by the USER command; if the user wishes to protect the higher user areas, he may set this symbol to the highest area normally accessable SYSFLG This is the option character for the DIR command line which is used to specify that DIR search All Files (both $SYS and $DIR) for its display; the distributed default for this is 'A' SOFLG This is the option character for the DIR command line which is used to specify that DIR search ONLY the $SYS files for its display; the distri- buted default for this is 'S' SUPRES Set SUPRES to TRUE to suppress printing the user number when the user is under User Number 0 or set SUPRES to FALSE to ALWAYS display the User Number with the CCP prompt; with SUPRES set to TRUE, a user on B: in user 0 sees 'B>' as the prompt, but with SUPRES set to FALSE, a user on B: in user 0 sees 'B0>' as the prompt DEFUSR This is the CCP-default user number which is searched in the command hierarchy for the COM files (distributed as 0); the DFU changes this temporarily until a Warm Boot or Cold Boot is done, at which time the search reverts to this value SPRMPT This is the CCP prompt character which indicates that a SUBMIT file is in execution; by default it is set to '$', so prompts like 'A$' appear during SUBMIT file execution CPRMPT This is the CCP prompt character which indicates that the CCP is awaiting a user console command; by default it is set to '>', so prompts like 'A>' appear during user input to the CCP NUMBASE This is the escape character used by those commands which require a DECIMAL number as an argument; placing this character after the number argument switches the base to HEXADECIMAL; for example, 'SAVE 15 MYFILE' can be expressed as 'SAVE FH MYFILE' if NUMBASE is set to 'H' (the default) SECTFLG This character constant is the suffix option for the SAVE command which specifies that sectors, as opposed to pages, are to be saved; the default value is 'S' FENCE This is the character printed to separate entries in a directory listing; it's default value is '|' No other customization is necessary unless the user wishes to change the commands disabled by RAS. This can be done by going to the command table 'CMDTBL' and changing the IF statement to the user's desires. -- Part B Usage Instructions and Explanation of Commands The following instructions are written with the assumption that the reader is quite familiar with how to use CP/M 2.2 and its CCP. CCPZ is written as a logical extension and slight modification of the CP/M 2.2 CCP philosophy and should be addressed as such. The CCPZ Command Hierarchy Search The first, and most basic thing, to learn about CCPZ is the order in which it searches for a COM file for execution or a file specified by the GET command. Under the CP/M 2.2 CCP, if the specified COM file command was not found on the current drive in the current user area, the CCP aborted with an error message. CCPZ, however, continues searching from this point a maximum of two more levels. This command hierarchy search was outlined above and is described here in further detail. 1. If the command is of the form 'COMMAND' and NOT 'd:COMMAND', the CCP-resident command list is searched for a match. If the match is found, the CCP-resident command is immediately processed. If the match is not found or the command is of the form 'd:COMMAND', the next step is taken. Note that the 'd:COMMAND' form is good for executing a command COM file which has the same name as a CCP-resident command (such as SAVE or DIR). 2. If the command is of the form 'd:COMMAND', disk drive 'd:' is temporarily logged in for the purpose of the command search. Otherwise, the currently logged-in drive is used. 3. Now the file named COMMAND.COM is searched for. If found, it is loaded into memory starting at 100H and executed. If not, proceed to step 4. 4. Now that the first search for COMMAND.COM has failed, the CCP checks to see if the user is under the current Default User Number. The Default User Number may be that set by the DEFUSR equate in the CCP or that set by the user via the DFU command. DEFUSR is in effect if DFU has not been issued since the last Warm or Cold Boot, and DFU is in effect if it was issued since the last Warm or Cold Boot. If the user is NOT under the current Default User Number, CCPZ temporarily logs him into it and searches the directory. If COMMAND.COM is found, it is loaded as described above and executed. If not, CCPZ proceeds to the next step. 5. The user is now in the Default User Number, and at this point, CCPZ checks to see if the user is on disk drive A:. If not, it temporarily logs into A: and searches the default user number of A: for COMMAND.COM. If found, it is loaded as described above and executed. If not, CCPZ prints the command name as an error message and returns to command input mode, aborting the SUBMIT file if COMMAND came from it. In all cases of the search above, if COMMAND.COM is found, after it is loaded into memory, CCPZ resets the user to his original disk drive and user number. Hence, the files referenced by the user by default are obtained from this environment. To illustrate this command hierarchy search, consider the following examples: Example 1: DEFUSR equ 0 {default user number is 0} B10> <-- User is on Drive B:, User Number 10 B10>ASM TEST.BBZ <-- User wishes to assemble TEST.ASM in Drive B:, User 10 <-- At this point, CCPZ looks on B:/10 for ASM.COM, fails, looks on B:/0, fails, and finally looks on A:/0; it finds ASM.COM here and goes back to B:/10 for the file Example 2: DEFUSR equ 0 and DFU issued B10> <-- User is on Drive B:, User Number 10 B10>DFU 5 <-- User Selects User 5 as default B10>ASM TEST.BBZ <-- As above <-- At this point, CCPZ looks on B:/10 for ASM.COM, fails, look on B:/5, fails, and finally looks on A:/5; it fails here also and prints ASM? as an error message Example 3: DEFUSR equ 0 B> <-- User is on Drive B:, User Number 0 B>ASM TEST.BBZ <-- As above <-- At this point, CCPZ looks on B:/0 for ASM.COM, fails, looks on A:/0, fails, and prints error message Example 4: DEFUSR equ 0 A10> <-- User is on Drive A:, User Number 10 A10>ASM TEST.AAZ <-- As above, but file on A: <-- At this point, CCPZ looks on A:/10 for ASM.COM, fails, looks on A:/0, fails, and prints error message -- The CCPZ-Resident Commands The following pages describe the CCPZ-Resident Commands. These are commands located within CCPZ itself which are executed from within CCPZ. The phrases and refer to ambiguous file name and unambigous file name as per the CP/M convention. Command: DIR Function: To Display a listing of the names of the files on disk Forms: DIR <-- Displays $DIR files DIR S <-- Displays $SYS files DIR A <-- Displays both $DIR and $SYS files Customization Variables: WIDE SYSFLG SOFLG FENCE Examples: DIR *.ASM <-- All $DIR .ASM files DIR *.COM S <-- All $SYS .COM files DIR *.COM A <-- All .COM files Notes: If a file is scanned for and no such name exists on disk, the 'No Files' message will appear. However, if a file is scanned for and the name exists as a $SYS file and $DIR files are being scanned for, no file name is displayed but the 'No Files' message does NOT appear. For example, if TEST.COM is a $SYS file and 'DIR TEST.COM' is issued, no message appears. If 'DIR TEXT.COM' is issued and TEXT.COM does not exist on disk, the 'No Files' message is displayed. Command: ERA Function: To Erase the specified $R/W files from disk Forms: ERA <-- Erase both $DIR and $SYS files Customization Variables: WIDE FENCE Examples: ERA *.ASM <-- Erase all .ASM files ERA *.* <-- Erase all files Notes: If a $R/O file is encountered, a BDOS error message will be displayed and the procedure is stopped. The user is unsure at this time as to which files have been erased and which have not and should check. Sorry for this problem! The ERASE command (to be given to SIG/M by RLC in the near future) is a solution to this problem. Command: LIST Function: To Print the specified file on the CP/M LST: device Forms: LIST <-- Print the file (no paging) Customization Variables: -None- Examples: LIST TEST.TXT <-- Print TEST.TXT on LST: Notes: If the file has a $SYS attribute, it will be found as well as those with $DIR attributes. Command: TYPE Function: To Print the specified file on the CP/M CON: device Forms: TYPE <-- Print the file with the paging deflt TYPE P <-- Print the file with the paging deflt negated Customization Variables: NLINES PGDFLT PGDFLG Examples: TYPE TEST.TXT TYPE TEST.TXT P Notes: When the display pauses during paging, type any char to continue or ^C to abort. ^S also works. Command: SAVE Function: To Copy the TPA starting at 100H to disk Forms: SAVE <-- in DEC SAVE H <-- in HEX SAVE S <-- Number of sectors SAVE H S <-- Number of sectors Customization Variables: NUMBASE RAS Examples: SAVE 15 MYFILE.TXT <-- 15 pages saved SAVE FH MYFILE.TXT <-- 15 pages saved SAVE 10H MYFILE.TXT S <-- 16 sectors (8 pages) saved Notes: -None- Command: REN Function: To Change the name of a disk file Forms: REN = Customization Variables: RAS Examples: REN NEWFILE.TXT=OLDFILE.TXT Notes: -None- Command: USER Function: To Change the current user number Forms: USER <-- in DEC USER H <-- in HEX Customization Variables: -None- Examples: USER 15 USER FH USER 0 USER <-- Same as USER 0 Notes: -None- Command: DFU Function: To Temporarily Change the default user number for the command hierarchy search Forms: DFU <-- in DEC DFU H <-- in HEX Customization Variables: -None- Examples: DFU 15 DFU FH DFU 0 DFU <-- Same as DFU 0 Notes: See above for explanation. Command: JUMP Function: To "call" the subroutine at the specified page address Forms: JUMP
<--
in HEX Customization Variables: NUMBASE RAS Examples: JUMP E000 or JUMP E000H <-- Jump to E000H JUMP <-- Jump to 000H JUMP 0 <-- Jump to 000H Notes: JUMP performs a subroutine "call", so the called routine may return to the CCPZ by either a RET or a Warm Boot. Command: GO Function: To "call" the subroutine starting at 100H Forms: GO <-- Execute reentrant at 100H Customization Variables: RAS Examples: GO *.ASM <-- Assuming XDIR is loaded, gives directory of *.ASM Notes: This command is identical in function to JUMP 100H. Command: GET Function: To load a file from disk into memory starting at the specified page Forms: GET
<--
in HEX Customization Variables: NUMBASE RAS Examples: GET 8000 TEST.80 <-- Load TEST.80 starting at 8000H GET 100 TEST.80 or GET 100H TEST.80 <-- Load TEST.80 starting at 100H GET 0 TEST.80 <-- Load TEST.80 starting at 000H Notes: GET searches for the specified file according to the same command hierarchy search employed by the CCPZ command scanner. Hence, if the user is on B:/10 and the file is on A:/0 with the current default user number at 0, GET will search from B:/10 to B:/0 to A:/0 in looking for the file. -- CCPZ Error Messages The following are the error messages issued by CCPZ and their meanings. Message Meaning ? Printed after a command or an argument means that such was invalid No File From DIR, this means that DIR did not locate any files Also from ERA with the same meaning All? Issued in response ERA *.*, asks the user is he really wants to erase all the files. Unlike under the original CP/M 2.2 CCP, single character input is required (Y or y for yes and anything else for no) with NO to end the line Full From SAVE, means that there is not enough space on disk From GET or command load by CCP, means that there is not enough space in memory File Exists From REN, means that the new file name specified already exists on disk