;
                                   ZPATCH.COM                                 

             Size (recs) CRC   Version    Author/Latest Issue      Disk
               9k (71)   0D28  1.3        Steven Cohen 4/88        Z3COM13

  1- Syntax  2- Installation  3- Notes  4- Help File  5- Error Messages       

   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.

   To view extensive help on the ZPATCH commands, type:

   M - the Movement commands       E - the Edit command
   S - the Search commands         U - the Utility commands
                                   Y - the System commands
:1

   Syntax:  ZPATCH 	<-- not recommended.  You'll simply be prompted for
		             a file name.

            ZPATCH UFN	<-- patch the specified file.  May use DU: or DIR:
: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.


 # - 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 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.

 X  - eXit 

   Exit the ZPATCH shell.  For your convenience Control-Q also works here.

 R  - Run (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.
:2

Installing ZPATCH:

   Under ZCPR3.0, ZPATCH is installed using Z3INS as follows:

		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.
:3
ZPATCH Notes:

   a. 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  it is not "track and
      sector" oriented and permits paging sequentially through a file.

   b. 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 (if the patch doesn't hang your system).

   c. 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 certain types of files.


ZPATCH Notes (continued):

   d. Vs 1.3  is  a  ZCPR33  type-3 utility  that  can  be linked to origin at
      addresses other than  100h.   It  automatically  sets  the  offset  when 
      working on Z33 type-3 .COM files to their correct load address.

                         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.


                           Numeric Input (continued):

      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.
:4

                              ZPATCH.HLP

             Size (recs) CRC   Version    Author/Latest Issue      Disk      
              20k (149)  C492  1.0        Steven Cohen 3/87        Z3HLP3
==============================================================================

   Z-System Help file for ZPATCH.COM.
:5
                            ZPATCH 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 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.
