CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / jsage / znode3 / uploads / zpatch13.lbr / ZPATCH.HZP / ZPATCH.HLP

Wrap

Text File | 1993-06-07 | 18.3 KB | 481 lines

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