RomWBW/Source/ZCCP/zccp.txt

The following is used by permission and remains copyright Randy Winchester.
===========================================================================

ZCCP Documentation, Version 1.0
by Randy Winchester <randy@mit.edu>

ZCCP Features

This documentation is provided to assist the user in getting a 
ZCCP system up and running.  It is not an exhaustive course on Z- 
System or ZCPR.  The following list details which ZCPR features 
are provided with ZCCP, and which ones aren't.

* ZCPR 3.3 compatibility.  ZCCP can run a wide range of utilities 
  an applications created for ZCPR 3.3 and ZCPR 3.4.

* TCAP.  A Z3T termcap file describing terminal characteristics 
  can be loaded into the system.  Z-System programs make use of the 
  TCAP for output to the screen - a big improvement over the old 
  method of patching individual programs with terminal control 
  codes.  TCAP files are loaded by the ZCCP LOADSEG command.

* Named directories.  Up to 12 user areas can be assigned names.
  Named Directory Registers (*.NDR files) are loaded by the ZCCP
  LOADSEG command.

* Command Search Path.  ZCCP will search for commands along a 
  user defined search path.  Up to six path elements 
  (directories) can be defined.

* Environment block.  Contains TCAP, Named Directory, and Path 
  information.  Also includes a map of active disk drives and 
  other system information.  The environment block can be viewed 
  with the Z-System SHOW utility.

* Flow control.  Conditional processing for batch files.  Relies 
  on Z-System IF.COM for setting the flow state.  Other flow 
  control commands (FI, ELSE, XIF, OR, AND) are resident.

* Multiple commands can be entered on the command line.  The 
  command line buffer will hold up to 225 characters.  Commands 
  should be separated by semicolons.

* Extended Command Processor.  If a command is not a built-in 
  flow command, resident command, or located on disk along the 
  search path, the command line is passed to an extended command 
  processor.  A typical extended command processor is ARUNZ, a 
  sophisticated batch file executor with alias features.  To use 
  a program as an extended command processor, rename it to 
  CMDRUN.COM and place it in the ROOT directory of your boot disk.

* Error handler.  In the event that the extended command 
  processor can't handle a command, control is passed to an error 
  handler.  Error handlers give information about the error 
  (instead of the useless CP/M "?" message) and allow the command 
  line to be edited and reused.

* Resident commands.  The following commands are built in:
    CLS  - clears the screen
    NOTE - text following the NOTE command is treated as a 
           comment.
    FI   - Flow control:  terminate the current IF level
    ELSE - Flow control:  toggle the flow state
    XIF  - Flow control:  exit all pending IF levels
    OR   - Flow control:  OR IF tests to set flow state
    AND  - Flow control:  AND IF tests to set flow state

* Shell stack.  Up to four shell levels can be defined.  Z-System
  provides a choice of several different shells.  Applications such 
  as terminal programs and word processors can also be assigned 
  shell status.

* ZCCP uses the LOADSEG command for direct loading of RSX files 
  that have not been GENCOMed.  Example: LOADSEG SAVE.RSX loads 
  SAVE.RSX.

There are some things that Z3Plus will do that ZCCP won't do.  

- ZCCP does not support a Flow Command Package (FCP).  It relies 
  on the transient IF command.  Other flow commands (FI, ELSE, XIF, 
  OR, AND) are resident in ZCCP.

- A Resident Command Package (RCP) is not implemented.  CLS and 
  NOTE are resident in ZCCP.  All other commands must be loaded 
  from disk.  This isn't as much of a handicap as it might sound 
  if you have a fast RAM drive to store frequently used commands.

- ZCCP can not load type 4 programs (used with ZCPR 3.4).  It 
  loads standard COM files at 100H, and type 3 programs that load 
  in high memory.  Most type 4 programs have type 3 or COM 
  equivalents, so this should not be a problem.

- ZCCP can not reexecute loaded programs.  This trick is usually 
  performed on Z-Systems with a GO command that jumps to 100H.  
  Since ZCCP also loads at 100H, a GO command would only restart 
  ZCCP.

ZCCP Files

Three files are included in ZCCP.ARK:

 File name      Size  Description
 ============   ====  ==========================================
 CCP     .COM   3k    ZCCP replacement for CCP.COM
 LOADSEG .COM   3k    Loader for named directories and termcaps
 ZINSTAL .ZPM   1k    Segment containing environment information

Getting Started - Preparing a Boot Disk

Format a system boot disk using the same proceedure that you normally
would.

Copy the files from ZCCP.ARK to user area 0 of the newly 
formatted disk.

Copy CPM+.SYS (some systems may use a slightly different name for this
file) to user 0 of the boot disk.  The CPM+.SYS must include the BDOS
segments from ZPM3.  Use the ZPM3 MAKEDOS utility to overlay your
system file with ZPM3.  (Commodore 128 users must generate a new
system using the ZPM3 BDOS segments.  The MAKEDOS utility does not
work properly on a C128.)

Locate a copy of a Z-System alias utility.  A good one is 
SALIAS16, although others should work also.  Copy it to user 0 of 
the boot disk.

At this point, reboot the system with the new system disk.  After the
system boots, you won't be able to do much with it.  The only resident
commands are CLS and NOTE, and ZCCP can only locate commands if they
are prefixed with the drive and user number.

The next step is to create a startup alias.  When ZCCP boots, it 
looks for a file named STARTZPM.COM and executes commands from 
it.  STARTZPM.COM is created with a ZCPR alias utility.  Here is 
a listing of a STARTZPM.COM created with SALIAS:

     =============================================================

     A0>SALIAS STARTZPM

     15:                ; Logs the ROOT directory (A15) on the 
                        ; current drive.

     LOADSEG NAMES.NDR TCAP.Z3T
                        ; LOADSEG loads the Named Directory Register
                        ; and TCAP.
                        ; Directories can now be referred to by 
                        ; name, as in the next command:

     SETPTH10 /C COMMANDS RAM2 WORK $$$$ $$0 ROOT
                        ; SETPTH sets the command search path.  
                        ; The /c option first clears any existing path.
                        ; Directories are then listed in the 
                        ; order searched.  In this case, COMMANDS 
                        ; is a 64K ramdisk (drive/user F0) where
                        ; frequently used commands are stored.  RAM2 is 
                        ; an additional RAM disk. (drive/user M0).
			; WORK is a standard 3.5" floppy disk
                        ; drive, (drive/user C15) where some 700K 
                        ; of utilities and applications are 
                        ; located.  $$$$ refers to the currently 
                        ; logged drive and user area.  $$0 refers 
                        ; to user area 0 of the current drive.  
                        ; The ROOT directory is on drive A, user 
                        ; 15, where startup utilities and system 
                        ; files can be found.

     AUTOTOG ON         ; Turns on keyboard control of ZPM3 Auto 
                        ; Command Prompting.  Auto Command 
                        ; Prompting is toggled by entering CTRL-Q.

     COMMANDS:          ; Logs the commands directory.

     IF ~EXIST CP.*     ; Test to see if commands are loaded.  
                        ; This line reads:  "If the CP command 
                        ; does not exist . . ." and sets the flow 
                        ; state to true if the file doesn't exist.
        C1:CP C1:*.* F0:
                        ; ". . . copy all of the commands in 
                        ; drive/user C1 to the commands (F0) 
                        ; directory . . ."
     FI                 ; ". . . end if."

     ROOT:              ; Log the root directory (A15).

     CP C:ZF*.* M0:     ; Copy ZFILER.COM and ZFILER.CMD to the 
                        ; REU2 directory (M0).

     VERROR             ; Install VERROR error handler.

     DATE S             ; Set the system time and date.

     ZF                 ; Invoke ZFILER as a shell.

     =============================================================

Of course, your STARTZPM alias will vary depending on the 
hardware you need to support, your software preferences, and your 
work habits.  This alias is close to the upward size limit that 
ZCCP can handle based on the capacity of the multiple command 
buffer.  At the very least, I recommend an alias that will set up 
a search path and load a TCAP.

Actually, I put the cart before the horse in this example.  If 
you try to reboot your system with the LOADSEG command as listed, 
you'll notice that you don't have a NAMES.NDR file.  There isn't 
one distributed with ZCCP either.  Z-System utilities won't let 
you edit the NDR either, since the buffer for it hasn't been 
created yet.  This turned out to be a nasty chicken/egg 
situation, hopefully solved by the inclusion of a sample 
NAMES.NDR file containing simply A0:SYSTEM and A15:ROOT.

At this point, you should have a mostly functioning ZCCP system disk.
Reboot the system with the new disk.  You might want to correct any
problems with it or tweak it to perfection before moving on.

List of Z-System Utilities for ZCCP

Some of the following utilities are essential, others are nice to
have.  The version numbers listed are the latest known versions at the
time that this documentation was written.  Utilities can be found on
ZNode BBSs, and some of them are available on Internet anonymous ftp
sites (Simtel20 or its mirror sites).

SALIAS16  - already mentioned in the example above.  SALIAS (or 
one of the other ZCPR alias utilities) are essential.

SD138B    - excellent DIRectory utility.  SD offers many 
different types of sorts, list formats, etc., displays date 
stamps, and supports output to a file.

MKDIR32   - utility for manipulating directory names and Named 
Directory Register (*.NDR) files. 

ERASE57   - erases files.

ZFILER10  - a file management shell that can launch applications.  
It is programmable in that it can execute user defined macros 
from a file.  Multiple files can be "tagged" and operated on by 
other programs.  ZFILER is an excellent program, sort of a GUI 
desktop without the slow graphics.

SETPTH10  - used to set the command search path.  Essential!

VERROR17  - error handler that displays the command line for 
reediting.  VERROR17 is the only error handler that I found that 
works with ZCCP.

ZEX50     - Z-System EXecutive is a powerful batch file processor 
that replaces the CP/M SUBMIT command.

LBRHLP22  - Z-System Help utility displays help files.  Help 
files can be crunched (*.HZP), and/or loaded from a HELP.LBR 
library.

ARUNZ09   - runs an alias script from a text file.  ARUNZ is 
frequently used as an extended command processor.  To use ARUNZ 
(or any other executable utility) as an extended command 
processor, rename it to CMDRUN.COM.

VLU102    - Video Library Utility views or extracts files from 
libraries.  Versions of VLU above 1.02 do not work reliably with 
ZPM3/ZCCP.

Z33IF16   - is the IF.COM discussed in the section on flow control.

SHOW14    - displays an immense amount of information about your 
Z-System.  SHOW also includes a memory patching function.

ZCNFG24   - configures Z-System program options.  Most Z-System 
programs are distributed with a configuration (*.CFG) file that 
produces a menu of configuration options when run with ZCNFG.

ZP17      - Z-System Patch utility edits files, disk sectors, or 
memory, and includes a built-in RPN calculator and number base 
converter.

ZMAN-NEW  - This is a manual describing Z-System features in 
depth.  It is based on earlier versions of Z-System, and is a 
little dated, but otherwise contains information that you won't 
find anywhere else.  Not everything in the manual applies to 
operation of ZPM3/ZCCP, but with the documentation presented 
here, you should be able to get a good idea of what works and 
what doesn't.

A TCAP termcap file for your system - This file is essential if you
want to use any ZCPR programs that need a TCAP.

ZCCP Technical Notes

ZCCP is a replacement CCP that implements ZCPR 3.3.  It loads at 
100H and is stored in the bank 0 CCP buffer for fast reloading as 
does the standard CCP.  By contrast, Z3Plus loads into high 
memory and can be overwritten by transient commands, requiring 
reloading Z3Plus from disk.  Because ZCCP replaces the CCP, a 
ZCCP system has more TPA (transient program area) than a Z3Plus 
system.  A ZCCP system on the C128 has more than 57K of TPA, 
almost the same amount as a standard C128 CP/M system.

This should be enough information to get started with ZPM3/ZCCP.  
Set up a boot disk, experiment with some Z-System utilities, read 
ZMAN-NEW, and get some applications running.  You'll agree that 
ZPM3/ZCCP breaths new life into CP/M.

*******************************************************************************
*  Randy Winchester  *  randy@mit.edu  *  PO Box 1074, Cambridge, MA  02142   *
*******************************************************************************