;
                                             
                                   Z   P           
                                             
                                Version 1.4

            A ZCPR33+ Screen-Oriented File/Disk/Memory Patcher

                          I -->  Installation    
                          O -->  Overview        
                          S -->  Syntax          
                          R -->  Running ZP      
                          M -->    Memory Mode   
                          D -->    Disk Mode     
                          F -->    File Mode     
                          X -->    String Search 
                          E -->    Record Edit            
                          H -->    HP Calculator 
                          Q -->    HP Quik Ref    
                          K -->    Record Cache  
:I
 Installation 
 
The distribution version of ZP is supplied ready for use in ZCPR33+ 
environments.  

 Configuring ZP 

ZCNFG may be used to configure ZP to alter the operation of the program to 
suit the user.  Default values for the starting memory mode address, the 
ASCII record character display mode and the menu box line graphics may be 
configured.
:O
 Overview 

ZP (Zcpr33+ Patcher) is a Z80 screen-oriented record editor-patcher.  
ZP.COM, a type 3 version executing at 100h, and ZP.3OM, a type 3 version 
executing at 8000h, require ZCPR33+ or Z3PLUS and will not run under 
straight CP/M or ZCPR3.0.  ZP.4OM, a type 4 version, executes only under 
ZCPR34+ or Z3PLUS.  All versions of ZP are BGii-compatible.  They all 
require an extended Z3TCAP (as defined by VLIB4D+) and also require that 
the ZCPR3 wheel byte be set.  

ZP was originally loosely based on SUPERZAP, aka SPZ or ZAP33, and was 
developed as a work-alike for Steven Cohen's great ZPATCH10 that, in 
addition to editing file records, would support screen-oriented editing of 
memory and disk records as well.  ZP is intended to complement rather than 
replace ZPATCH, as well as to complement Rob Friefeld's excellent BCOMP and 
VCOMP (especially when they are patched to use the ZPATCH command set.)  In 
order to keep ZP relatively simple and only 8k in length (except for the 
type 4 version), it lacks ZPATCH's comprehensive string search options and 
does not have a command to send the current record to the printer.  Unlike 
ZPATCH, ZP is a simple transient utility and not a shell.

ZP has a one-record cache for temporary record storage and can move the 
cache contents between file, memory and disk records.  This allows you, for 
example, to take a one-record Z3TCAP.Z3T file and patch it into memory in 
the ZCPR3 environment.  

ZP also contains the powerful and full-featured HP12 RPN programmer's 
integer calculator, which may be called up in file, disk, memory or record 
edit modes (even during the editing process), to perform, save or recall 
the results of integer calculations or logical operations in hex, decimal, 
binary, or character modes. 
:S
 Syntax 

While ZP allows the user to freely switch among modes during program 
operation, it also may be instructed to come up in the desired initial mode 
by using the following command line syntax:

     ZP [hex_addr]  - Memory mode at hex address
     ZP dir:        - Disk mode
     ZP [dir:]afn   - File mode 

     ZP //          - Display syntax help screen
:R
 Running ZP 

Except for the HP calculator, ZP is menu-driven and uses commands similar 
to ZPATCH10, so it should require little in the way of instruction.  More 
specific information about the operation of each mode may be found in the 
sections below.  

Several commands, however, do not appear in the menu.  There are several 
alternate exit commands, for example.  While the 'Q' command is the only 
exit command shown in the command menus, 'X' and ESC are also available as 
alternate exit commands.
 ASCII Record Display Mode 

ZP can display characters in the ASCII part of the record display in one of 
two user-selectable ways.  ZP's distribution default ASCII display mode 
displays only the actual displayable characters, displaying all other 
characters as '.'s.  This type of display, typical of DDT, is relatively 
uncluttered but it is more difficult to read disk directories that have 
attribute bits of the filenames set and to read WordStar files.  

Alternately, ZP can be commanded to filter the high bits of the characters 
being displayed, converting some non-ASCII characters to displayable 
characters and displaying all other characters as '.'s.  This type of 
display, typical of PEEK, contains more non-'.' characters.  While it can 
often appear more cluttered, it is easier to read disk directories and 
WordStar files in this mode.  

There is a ZCNFG-configurable flag that controls the ASCII display mode 
default.  During operation, the user can toggle the type of ASCII display 
desired by using the non-menu command Control-A (^A) at any of the main 
mode menus.
:M
 Memory Mode 

Memory mode is ZP's default mode of operation when no other mode is 
specified on the command line.  If no starting address is specified on the 
command line, the address of the ZCPR3 environment is the default starting 
address for the ZP display, but a different default starting address, such 
as 100h, may be configured if desired.  

If you include a starting address on the command line (up to 4 hexidecimal 
characters with NO non-hex characters), ZP will begin its display at the 
memory record containing the specified address.  A subsequent edit command 
will also begin at the specified address.  

ZP uses the command buffer, starting at 0080h, as its working record 
buffer, so whenever you view the command buffer record, you will actually 
be looking at a copy of the record that was previously viewed.  Note how 
the command buffer display differs as you step through it from opposite 
directions.  When it is displaying the command buffer contents, ZP also 
displays a special header to remind you that you are viewing the command 
buffer, as it is generally inadvisable (and usually futile) to attempt to 
edit the command buffer contents.

The 'T' (Top of Memory) command displays the highest memory record (FF80h-
FFFFh) and the 'B' (Bottom of Memory) command displays the first memory 
record (0000h-007Fh).  The 'A' command allows you to select the address of 
a memory 'record' to view.  ZP will display the 128 byte 'record' 
containing that address and if the edit mode is subsequently selected, the 
edit cursor will be positioned at the specified address.
:D
 Disk Mode 

When you select the drive you wish to access in disk mode, you may also 
specify a user area, using either a DU: or DIR: specification.  The 
specified drive/user then becomes the default for any subsequent file 
accesses.

ZP starts the disk mode display with the first directory record.  Other 
records may be selected by block, record, or track.  

Floppy disk system track records may be displayed by selecting track 0 or 
by stepping back from the directory.  Hard disk system records may be 
displayed when the 'first' disk (a DPB OFFSET of less than 10) is logged 
in.  Otherwise the display is limited to the actual logged disk tracks.  
When stepping past the first or last track or record of the disk, ZP will 
wrap around to the other end of the disk.
:F
 File Mode 

The drive/user contained in any filename specification becomes the default 
for any subsequent file or disk accesses.  

When wildcard filenames are entered, ZP will display the first file found 
in the directory that matches the specified ambiguous filename.  If the 
filename entered is a COM file, the file record addresses will 
automatically have a display offset of 0100h added so that the first file 
record will start at a display address of 0100h.  Other file types will be 
displayed starting at an address of 0000h (offset = 0).  The 'O' (Offset) 
command allows you to change the display offset as desired.

                   ZSDOS Path Search Caution!

When operating under ZSDOS with DOS path searching enabled, you may find 
that when you specify a non-existant file, ZSDOS will find a file of the 
same name on another drive on the DOS path.  ZP will display that file, but 
the header will still display the selected drive rather than the drive on 
which the file was actually found!  While ZP is still logged into the 
selected drive, ZSDOS, not ZP, found the requested file on the different 
DOS path drive and ZP has no way of knowing that.  The moral is that if you 
are operating under ZSDOS with DOS path searching enabled, be sure that a 
specified file exists where you expect it before you try editing it!
:X
 String Search 

ZP's string search function is similar to ZPATCH's, but in order to hold 
down the size of the code, it is not as extensive and has no options.  
Strings to be located may be entered as hex or ASCII characters or any 
combination.  ASCII strings are entered delimited by single or double 
quotes and will be automatically capitalized.  Hex characters are entered 
delimited by commas.  Both single and double quote characters must be 
entered as hex characters.  The remainder of the terminal display line 
after the prompt, about 45 characters, may be used for character entry.  
For example, the entry:

     'Fil',65,6e,61,"me" will create the search string 'FILENAME'

A few compromises and assumptions have been made so that the same search 
routine may be used in all situations.  When doing the search, ZP will 
first compare a search character with the buffer character without regard 
to ASCII case.  If no match is found, the buffer character will be 
capitalized (if ASCII) and another comparison made.  This allows you to 
search for text in WordStar files or disk directories without worrying 
about case or high bits while still retaining the ability to do searches 
for hex characters such as command or address characters.  For example:

     'Filename' will match 'FILEN','A'+80h,'ME' or 'FILENAME' 
          (where the 'A' has the high bit set), while 

     'Filen',E1,"me" will match 'FILEN','A'+80h,'ME', but not           
          'FILENAME' (specifically insisting on an exact match 
          for E1h, which is 'A' with the high bit set).

As a result of this relatively simple search method, hex search characters 
that happen to also be lower case characters will match both exact and 
'capitalized' characters, which might result in an occasional false 
positive match.  For example 65h ('e') will match both 65h and 45h ('E').

String searches may be stopped at any time by entering any character.  Disk 
mode string searches will continue until a match is found or until you stop 
the search, wrapping at the last track back to the first track.  

When the 'C' command is used to continue a search, the search will begin 
from the address of the last match if it is located in the record currently 
displayed, otherwise it will begin at the beginning of the current record.

When a string is found, the record in which it is found will be displayed 
and if the edit mode is then selected, the edit cursor will be positioned 
at the start of the found string.  If a string is not found, the current 
record will be redisplayed.
:E
 Record Edit 

ZP, like ZPATCH, uses the WordStar diamond keys to control the cursor 
during editing.  The arrow keys defined in the Z3TCAP are mapped as 
alternate cursor control keys, even though they are not shown in the edit 
mode command menu.  For some terminals with arrow keys that generate more 
than one character (such as ANSI terminals), the arrow key definitions in 
the Z3TCAP will probably be the WordStar diamond keys.  Since the actual 
physical arrow keys will generate commands rather than move the cursor in 
that case, they can't be used, and will usually cause an exit from ZP if 
pressed (since they usually contain an escape character, which is an 
alternate ZP exit character.)

When the edit mode is entered following a string search or an address 
specification, the edit cursor will be at the beginning of the found string 
or at the specified address.  Specifying the desired edit address before 
entering the edit mode is a quick way to reach any desired address in the 
record being edited.  The ESC key toggles between Hex and ASCII edit modes.
ZP uses the ZPATCH commands to exit the record edit mode.  Enter 
^Q to quit without saving the changes, and enter ^W to save the 
changes and exit. 
:Q
 HP Calculator Quick Reference 

ZP contains the powerful and full-featured HP12 RPN programmer's integer 
calculator, which may be called up at any time (even during the editing 
process) to perform, save or recall the results of integer calculations or 
logical operations in hex, decimal, binary, or character modes. 

The calculator is both invoked and exited by entering ^C.  Since the 
calculator retains all register information as long as ZP is running, 
calculator registers may be used to store reference data between other ZP 
operations.  The calculator may also be invoked during record editing 
operations without affecting the editing process in any way.
 HP12 Command Summary 

    ^X         Clear entire stack
     BS        Delete last character
   <RET>       Enter number into register X
     =         Exchange the contents of X and Y
     L         Restore last X value
     < or ,    Roll stack down one level
     > or .    Roll stack up one level
     Sn        Store contents of X in memory register n (0-5 or R)
     Rn        Recall contents of memory register n to register X
    ^C         Exit HP12

 HP12 Math Function Summary 

     +         Addition, X=Y+X
     -         Subtraction, X=Y-X
     *         Multiplication, X=Y*X
     ^         Exponentiation, X=Y^X  (Y to the power X)
     /         Integer quotient, X=INT(Y/X)
                    - Remainder in Register R=X*(Y/X-INT(Y/X)) 
     &         Bitwise AND, X=Y&X
     |         Bitwise OR, X=Y|X
     ~         Negation [2's complement], X=~X
:K
 Record Cache 

ZP provides a one-record buffer into which you can copy the currently 
displayed record.  You can later exchange the cached record with the record 
being currently displayed.  This allows you, for example, to experimentally 
edit a record while maintaining a copy of the unedited record in the cache 
buffer.  Note that when you exit ZP, the contents of the cache buffer will 
be lost, so if you wish to preserve a record, exchange it with a record 
from a 'holding' file of at least one record in length that you have 
previously reserved for record storage (ZP does not create files by 
itself).  You can also save a cached record in an unused 'record' in 
memory, using SAVE to save the memory record to a file after you exit ZP.

The second ZP status line displays the the origin of the current cached 
record.  Copying a record into the cache will overwrite the previous 
contents of the cache.  Performing a cache copy or exchange operation 
automatically returns you to your previous mode and updates the current 
record display.
:N:ZP-RPN.HLP
:H:ZP-HP.HLP