;

                          ZPATCH Version 1.0

			O - Overview 
			I - Installing ZPATCH	

M - Movement Commands               	S - Search commands
E - the Edit Command                	U - Utility commands 
			Y - System commands

 			N - Note on numeric input
			R - Error Messages
:O


Program:  
	ZPATCH

Syntax:
	ZPATCH		    (not recommended.  You'll simply be prompted for
			     a file name.)
	ZPATCH UFN	    (patch the specified file.  May use DU: or DIR: 
			     form.)


			PHILOSOPHY

       ZPATCH is a file-oriented byte editor similar in function to the 
public domain program EDFILE.  It enables you to patch a file 
byte-by-byte. This can be useful when you obtain documented patch 
addresses known to affect a program in certain ways.  It is often 
easier to make a patch or two to a program than to reassemble it, and 
if you don't have source code, patching is the only way.

	Other programs may be used to patch, such as DEBUGGERS like 
DDT, or DISK EDITORS like DU3.  ZPATCH is much easier to use than a 
debugger because it requires you to learn no unusual syntax, and 
because there is no need to calculate the number of 256-byte "pages" to 
be saved after the patch has been made.  ZPATCH is also easier than a 
disk editor because these are "track and sector" oriented and therefore
"user-disorienting".  ZPATCH, on the other hand pages sequentially 
through a file which is most convenient for most patching jobs.  The 
other tools have their uses, but patching files is not what they're 
meant for.



			SPECIAL FEATURES

	ZPATCH offers many special features not previously found in 
such programs.  First, ZPATCH is a ZCPR3 shell, and as such allows you 
to suspend execution of ZPATCH, give any valid system command line, and 
then be put right back where you left off.  This can even be done 
with a single keystroke if the file you are patching is a .COM file.  
This enables you to interactively patch and see the results of your 
patches until the program works as you desire (assuming the patch you 
have made does not cause your system to hang).

	ZPATCH allows you to print out each sector displayed.  You can 
change files on the fly without leaving ZPATCH.  You can search for 
particular bytes or byte patterns, or ASCII strings, with options to 
disregard case, compare on 7 bits only, or in fact, on any combination 
of bits.  ZPATCH allows you to set the OFFSET or apparent address at
which bytes appear.  The offset is automatically set for you for 
certain types of files.


			WARNING TO USERS

	Patching programs can destroy them if you make a mistake.  Always
patch a COPY of a file and keep the original intact.  Better yet, write 
yourself a ZCPR3 alias that will copy a file elsewhere before ZPATCH is
allowed to work on it.


:I



Installing ZPATCH

	ZPATCH is installed for your system using Z3INS.  The command line
to do this is:
		Z3INS xxx.ENV ZPATCH.COM

where xxx is the name of your Environment descriptor, usually SYS.ENV

		ZPATCH PATCH LOCATIONS

	These patch locations in the first sector of ZPATCH.COM control 
ZPATCH shell functioning.  It's probably best to put ZPATCH in the ROOT:
Directory and set 010B to 0FFH, but you may prefer another configuration.

Location      Default Value	Comments

010BH		0FFH		; 0FFH if zpatch.com will be located in
				; root directory, 0=NO

010CH		0		; if 010BH is 0, should system search 
				; the path for zpatch.com? 0=NO 0FFH=YES

010DH		15		; if 010BH and 010CH are both 0
		 		; make this the user area where
				; ZPATCH.COM is to be located
010EH		0		; and this the drive (A:=0, B:=1)

010FH		0		; make 0FFH to allow chaining to this
				; help file, leave at 0 to disable feature



You can easily use ZPATCH to patch ITSELF!

However, one word of caution.  Since ZPATCH is a shell, do not expect the
patches you have made to take effect immediately.  Rather, make the
patches, quit ZPATCH, then run it again and the patches will be in 
effect.  Actually, you COULD see the effects by EXECUTING ZPATCH
with the 'X' or 'Z' commands, but it would be very confusing, as upon
exiting, you would reenter an unpatched level of ZPATCH.
:R
Error Messages:

Shell stack error  
	Your system must have a shell stack and it must support 
at least 32-byte shell stack entries or you will get this error.  Most 
ZCPR3 implementations support these features, but if yours doesn't you 
won't be able to use ZPATCH.
	You can also see this message if your shell stack is full with
other shells beneath it when you invoke ZPATCH.  Removing some of these 
other shells will allow you to run ZPATCH.	

Ext. FCB Error
	It is assumed your system supports the External File Control 
Block feature.  Most ZCPR3 systems do, but if yours doesn't you won't 
be able to run ZPATCH.

Why did you rename ZPATCH?
	ZPATCH is a perfectly wonderful name.  Why change it?  
Seriously, you may do so, but if you attempt to rename it longer than 
six characters ZPATCH won't run.
:N
Note on Numeric Input

Many commands described below cause prompts to be issued that require 
you to input a number.  ZPATCH can read inputs in Decimal, Hexadecimal, 
or Binary notation.  Each prompt displays the default notation that 
ZPATCH is expecting like this:

		Enter OFFSET (HEX):

This tells you that if you simply enter the number without a trailing 
indicator it will be interpreted as a HEX number.  So in the above 
example if you wanted to enter the Hexadecimal number 200H (which 
equals 512 decimal or 1000000000 binary) you would enter either 

200		(hex - default),	
512#		(decimal) or 
1000000000%	(binary).  

If HEX is not the default and you wish to enter Hex then follow the 
number with an "H" as in 200H or F200H.  


In other words "#" is the indicator for decimal, "%" for binary and "H" 
for hex. If this confuses you just answer the prompts with the default 
notation which is the most logical most of the time.  Addresses and 
byte values are most easily given in HEX.  Number of times to repeat
a search is easier for most people in DECIMAL and that's the way ZPATCH 
does it.

Please note that none of the above discussion applies to the EDIT
mode of ZPATCH which is explained elsewhere.  All numbers there are
assumed to be HEX.

The maximum number that can be entered is 0FFFFFF hex or
16,777,215 decimal.  Entering anything larger wraps around to 0.


:M

		   COMMANDS FOR MOVING AROUND THE FILE

< or . - Forward one sector
> or , - Back one sector

These are the main commands for moving around the file one sector at a 
time.  Note that ZPATCH considers the file to be a ring and if you go 
past the end you come around to the beginning and vice versa.

A - Goto Address

Jumps the display to the sector containing the address you input. This 
address takes into account whatever offset the program is working 
under. If you enter the edit mode now, patching will begin at the 
address you specified. 

B - Bottom of File

Jumps the display to the last sector of the file.  





R - Goto Record

Jumps the display to the Record number you input.  Note that the 
current record number and # of records in display are given in both 
decimal and hexadecimal notation at the top of the screen.

T - Top of file

Jumps display to the beginning of the file.  





:S
			SEARCH COMMANDS

S - Search

You are prompted to input a string that ZPATCH will search for.
This string you input must adhere to rules of syntax explained below or 
ZPATCH will not accept it.


C - Continue search	

Repeats again the last search command you issued.  All parameters 
entered on the original search remain in effect except that the 
continue search always starts from the current position even if the 
original search was from the beginning.  



			SEARCH SYNTAX RULES

ASCII strings MUST be entered delimited with double quotes 
(") at beginning and end.

Note that this means that a double quote cannot be entered directly as 
an ASCII character, but must be entered by using its HEX value (22) as 
described below.  Ascii strings are delimited from other elements of 
the search string with commas.

HEX bytes are delimited from each other and from ASCII strings with commas.

Enter Search String: "ZPATCH"
Enter Search String: 5A,50,"AT",43,"H"
Enter Search String: 1,2F,36,FF,D0,3,38,0,4

The first example searches for the same string as the second, illustrating 
the proper use of comma and double quote delimiters.


			SEARCH OPTIONS

Certain features of the search may be selected by the use of option 
characters which are appended after the string.  Options are delimited 
from the rest of the string by a semi-colon after the last character of 
the search string.

The following options are provided:

A - Start search from beginning of file.  (Otherwise starts from 
current position)

B - Search backward from the present position.

7 - Search considering only the lowest 7 bits of each character.  
This is handy for searching through files created with certain word 
processors. 

M - Search with certain bits masked off.  You will be asked for a 
byte mask value which you can input in HEX (default), BINARY, or DECIMAL.
For example to search for any bytes whose high nibble is 0C hex, you 
would select a value that is sensitive to the high four bits (on) and 
not the low four bits. That value is 11110000 binary or F0 hex.  The '7' 
command is just an easier way of selecting a mask of 01111111 binary or
7F hex.

S - Search skipping the first n occurrences of the selected string.
You will be prompted for n which can be any number in the range 0-255.

U - Search without regard for case, that is upper case is 
considered the same as lowercase for A-Z.

Examples of option searches:

"ZPATCH";u matches ZPATCH, zpatch, Zpatch or zPaTch.
"ZPATCH";ub does the same as the above but searches backwards.
"ZPATCH";ub7 as above but compares only the low 7 bits.

Aborting a search

A search can be aborted simply by typing control-C while the search is 
taking place.

Quick search help

A quick summary of search syntax is available by typing ?<RETURN> in 
response to the "Enter search string (or ? for help)" prompt.  


:E
			THE ZPATCH EDITOR

E - The edit command

From command mode the edit command puts you into the ZPATCH 
editor ready to patch individual bytes.  You will see a 
hexadecimal dump display like this one:

 ZPATCH 1.0  E2:ZPATCH.COM            Record # 00001 (0001H) of 00067 (0043H)

          00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F    0123456789ABCDEF
          -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --    ----------------
00 0100 - C3 10 01 5A 33 45 4E 56 01 00 F3 FF 00 0F 00 00   <...Z3ENV........>
00 0110 - 2A 09 01 CD DE 19 CD D2 17 3A 5D 00 FE 2F 20 06   <*........:]../ .>
00 0120 - 21 5C 09 C3 AA 01 CD 0C 1E 22 B1 09 28 05 7B FE   <!\......."..(.>
00 0130 - 20 30 06 21 75 09 C3 AA 01 11 10 00 19 22 B3 09   < 0.!u........"..>
00 0140 - CD BC 1D 20 06 11 87 09 C3 AA 01 11 07 00 19 7E   <... ...........~>
00 0150 - FE 20 28 06 21 96 09 C3 AA 01 CD 27 09 CD 73 21   <. (.!......'..s!>
00 0160 - ED 43 A4 0B CD C6 1C 20 23 CD DC 15 2A B3 09 ED   <.C..... #...*...>
00 0170 - 5B 91 0B 01 0B 00 13 ED B0 11 8E 0B ED A0 ED A0   <[...............>
|     |  \              this is the                    /    \  this is the   /
address   \- - - - - HEXADECIMAL DISPLAY - - - - - - -/      \ASCII DISPLAY /


	Dump displays look the same in EDIT and COMMAND modes 
but their different onscreen menus distinguish them.  When you enter 
the EDIT mode your cursor will be in the HEXADECIMAL DISPLAY on the 
byte you will be patching.  Normally this will be the first byte of the 
sector, but if you enter the editor immediately after a successful 
search the cursor will point to the first byte of the matched string, 
and after an A (Address) command the cursor will point to the byte at 
the selected address.  

	Notice the address display.  The first two digits will be greater
than zero only if the file length is greater than 64K (or if the offset is
large enough to make it appear so.  For any file shorter than 64K these two
digits can be ignored, and only the last four considered.  These four
digits are the ones commonly used to refer to CP/M and ZCPR3 patch points.
ZPATCH prints a space between the first two digits and the last four 
to help make this a little less confusing.


			CURSOR MOVEMENT

From EITHER SIDE of the display you can move from byte to byte within 
the sector using the Wordstar cursor diamond commands 

		^E-Up
	^S-Left	     ^D-Right
		^X-Down

This is same display is shown on the edit mode menu.
If your arrow keys are enabled within your ZCPR3 TCAP, these will also 
perform the same functions unless they duplicate one of the other Edit 
Mode command keys described below.

Please note that ZPATCH treats the display as a ring and moving 
the cursor beyond its limits simply wraps around to the other side.

 
			EDIT MODE COMMAND KEYS

Three commands control the basic functions of the Edit Mode on both the 
hexadecimal side and the ASCII side of the the display. 

^Q - Quit edit mode without writing sector back to disk.
	(Please note that the display you see after this command WILL 
reflect the edits you have made but they WILL NOT be written to disk 
unless you type the W command from command mode.  If you move to 
another sector the edits will be lost.  The W command in command mode 
is a "last chance" option to recover from inadvertently quitting the 
edit mode.)  A "Not Written" message will appear at the bottom of the 
screen to let you see that this is the case.

^W - Write sector to disk (automatically reverts to command mode)
A "Written" message will appear at the bottom of the screen letting
you know what has happened.

<ESCAPE> - Switches back and forth between the HEXADECIMAL and ASCII
displays.  This is the ONLY way to switch between displays.  The cursor 
keys will not do it.


			EDITING IN THE HEXADECIMAL DISPLAY

When in the hexadecimal display, besides the cursor and command keys 
described above, the only keys that will do anything are the numerals 
0-9, and the hexadecimal letter characters A-F (upper or lower case).  
When one of these is pressed the hexadecimal display is changed to the 
new hexadecimal value and, since this changes the ASCII value as well, 
that is also changed.  Note that ANY byte value can be entered from the 
hexadecimal side, even those that are not valid ASCII characters.

			EDITING IN THE ASCII DISPLAY

When in the ASCII display all keys except control keys will change the 
ASCII display, and also update the hexadecimal display with the correct 
value.  The ASCII display is much easier to work in when typing in 
character strings and words.  On the other hand not all byte values can 
be entered from the keyboard, and if you need to enter a untypable 
value you MUST do it from the hexadecimal side.
:U
			UTILITY COMMANDS

O - Enter Offset

ZPATCH automatically selects a logical offset for the type of file you 
are working with.  .COM files are offset at 0100H which is the normal 
address at which they are loaded into memory.  Z3 system segments are 
offset to the address at which they are loaded by the Z3 LDR command.  
Others are offset to 0.  You may change any of these with the O command 
as often as you like.

P - Print Sector

Puts the same hex dump display you see on screen to the printer.

W - Write sector

Although this will usually be done from the edit mode, you can also do 
it from the command mode.  This will be useful if you accidentally 
leave the edit mode without writing your changes to the disk.  After 
you exit the edit mode the message line contains a message, either 
"Written" or "Not Written" letting you know.
:Y
			SYSTEM COMMANDS


	These commands are available at all times, and give access to the
special features of the ZCPR3 system.  They are the ONLY commands 
available when a file has not been successfully opened for patching.

F  - Give File Name

Enter a new file name for patching.  The old file is closed and a new 
one opened.   

Q - Quit 

Exit the ZPATCH shell.  For your convenience Control-Q also 
works here.

X - Execute .COM file 

 If the file you are patching is a .COM file you may execute it from 
ZPATCH with the X command.  Upon finishing that program you will be 
returned to ZPATCH.  Please note, however, that if the program you are 
patching requires command line parameters you should use the Z command 
instead. 

Z - ZCPR3 command 

 You are shown a prompt similar to the ZCPR3 system prompt and you 
give ZPATCH a standard ZCPR3 command line, which your system then 
executes and upon completion of the command you are returned to ZPATCH 
still patching the same file in the same position.  There is one 
extended parameter option you have in this command line:

A $ character as the FIRST character in the command line is interpreted 
by ZPATCH as the name of the current command.  Thus if you are patching 
the file LZED.COM and want to supply a a file to edit with LZED in the 
command tail you can issue the command as LZED TEXT.FIL or simply
$ TEXT.FIL.  Please note that a space must follow the opening $.

H - Help

Chain to this help file.  HELP.COM must be available somewhere along
your ZCPR3 search path and ZPATCH.HLP must be located where HELP.COM can 
find it (either along the path or in a directory named HELP:) 

NOTE: This feature will only be enabled if the patch byte at 010FH 
is set to 0FFH.  If you are running a system without HELP.COM easily 
accessible you will probably be better off doing without it.   0FFH.  If you are running a system without HELP.