*** Almost Completely Superfluous Manual to ZAP 2.5 *** *** What is ZAP ? *** ZAP is an editor, designed to edit program files. That is why it cannot change the length of a file, and why it displays files both in ASCII and in hexadecimal code. It needs very little memory ( less than 25K ) and may be used on files of arbitrary size, to at least a megabyte. ZAP is a 'public domain' tool. Copy it and pass it on as much as you like. *** Why would I need ZAP ? *** For any number of reasons. Every time you want to know, and maybe to change, what is in a file that is not normally readable or printable, you will find yourself reaching for ZAP. Other possibilities: - Use it to change a default path in those irritating programs that do not know where to find your hard disk or ram disk. - Use ZAP to modify text in programs of which you do not have the source code, e.g. to correct spelling mistakes, or to translate messages. - Use it to find text in programs, e.g. to look at vocabularies of games (if they have not been encrypted). - Use it to look for hidden messages in programs, and experience the true hacker's thrill.... *** How do I use ZAP ? *** Very carefully. ZAP is a like a surgeon's knife: very handy to work with, but dangerous unless you know exactly what you're doing. As it may take only two keystrokes in ZAP to ruin any program, one to change a byte and one to write the changed data back to disk, I must advise you strongly to ALWAYS make a backup before experimenting. (Not that I ever do. But then I'm stupid. YOU should know better.) ZAP, however, also has the possibility to protect a file from changes on at least four separate levels, to prevent accidental changes. - If the disk is physically write-protected, or if the file is read-only, ZAP of course cannot change it. - If you specify the -r option on the commandline ZAP will not change the file. - If you lock the file during editing (click 'r/w' in the EDIT menu) ZAP will not allow any changes to the file until the lock is switched off again. - If you use the text filter, (click 'raw' int the EDIT menu) which displays only those bytes in the text field which are letters, digits, or punctuation marks, you cannot modify the file until you switch the filter off. The reason for this is to ensure that you write only when you have full information on what you're overwriting. - If you are in ESC mode ('ESC' displayed in the lower left corner of the screen) you cannot make changes to the displayed data. ( Note, however, that if you first make changes in EDIT mode, then switch to ESC mode, then get another chunk, ZAP will write the modified chunk to disk if you did not lock the file.) *** Starting ZAP *** ZAP may be named either ZAP.TTP or ZAP.TOS. It may be double-clicked, or called from a shell. If a commandline is passed to ZAP, it will be used, or else it will start with a dialog to ask for a commandline. In both cases the commandline must be of the same form: [ -r ] where is any legal TOS path/filename, and the optional -r (or -R) the read-only option. Examples: "c:\zap.ttp -r" will open the file ZAP.TTP in read-only mode. "zap.ttp" will open it normally. (If the file may be written to in TOS.) The commandline dialog page also explains how the single-line editor works. This single-line editor is used also for the search-string entry, so you may want to remember how it works. Not that there is anything difficult to it, it's all very logical. You can move the cursor, use backspace and delete, clear the line with and recall the original line with Undo. Pressing Return completes input, and if the line is empty ZAP exits. *So, the way to quit ZAP is to press at the command line dialog. If the file cannot be opened, or if the commandline contains the wildcards '*' or '?' ZAP gives an error message and lets you try again. *** The ZAP screen *** This consists of 4 parts: menubar, parameter section, file display, and command/message line. The top line is the menu bar. It displays the main command options you have at your disposal at that point. There are two menu bars, one for the EDIT mode and one for the ESC mode. You can see which mode ZAP is in by looking at the lower left corner of the screen. In EDIT mode, the menu bar shows: - ZAP 2.5 The name and version number of the program. Click this for some info about ZAP and for my address. - help Click this (or press ) to get a summary of the workings of ZAP in edit mode. - Esc Click this (or press ) to switch to ESC mode. - addr Click this to jump to an address in the file. This must then be entered in hexadecimal numbers. The first byte in the file has address 0, the last byte has address (filesize-1). - undo Click this (or press ) to read the displayed chunk from the disk into memory again. The situation is now as it was after this chunk was last saved. This will not affect changes that have already been saved to disk. - top Click this (or press ) to get the first chunk. - ^^^ ( arrows up ) Click this (or press ) to get the previous chunk. - vvv ( arrows down ) Click this (or press ) to get the next chunk. - end Click this (or press ) to get the last chunk. - raw|txt Click this to toggle the text only filter - useful if you are scanning a file quickly, looking for text. If the r/w flag was on, this will be set to r-o (for read-only) until you toggle the text filter off again. - r/w|r-o Click this to lock the file to prevent accidental changes during browsing, and click it again to unlock it. If the lock is toggled to unlock, the text filter is automatically switched off too. *If you attempt to change a file while r-o is in effect, this menu entry will flash briefly to remind you. - quit Click this to save the current chunk and exit to the file selection dialog page. In ESC mode, the menu bar shows: - ZAP 2.5, as above. Here also accessible by pressing Z. - Help - some info about ESC mode - UnEsc Click this, (or press Esc, or press U) to go back to edit mode. - Print Click this, (or press P) to print the current chunk. If the text filter is on, this will be used, otherwise non-printable characters will be replaced by a hyphen ( '-' ). (Since it is very unlikely that your printer knows the Atari graphics characters...) - Number Click this, (or press N) and you will be asked for a number of the chunk to display next. This must be entered in decimal. - Search Click this (or press S) to enter a string to search for. Depending on the state of ZAP, you will be asked to enter this string in HEX or as text. You may use control characters in the text state. In HEX state, the string must be specified as an even number of hexadecimal digits. As a null byte is used to terminate the string you can't search for anything following a null byte. Search is case-sensitive and starts at the current cursor position. - Find Click this (or press F). The same as above, but the search will use the previously entered string for that state. - Chunksize Click this, (or press C), to change the size of a chunk. The default value, 256, is also the maximum. - Quit Click this, (or press Q) to exit to the file selection screen. Besides these commands you can use the cursor keys and the mouse to position the cursor and to switch between states. Placing the cursor in the HEX field with the mouse will set the HEX state, placing it in the text field will set TEXT state. , , and work just as in EDIT mode. *NOTE: any action which brings a new chunk to the screen will first save the previous chunk to disk, if the file is not locked or in text filter mode. The parameter section of the screen shows you things like file name, size, cursor position, and current chunk and chunksize. If the current chunk differs from the one on disk, the (CHANGED) flag appears after the filename. *NOTE: once a chunk has been written to disk, ZAP doesn't remember whether it was modified before. The file display field. This consists of: - The offset field, where the offset from the start of the file is shown in hex. - The hex field, which shows the byte values of the file as hexadecimal numbers, 16 to a line. - The ascii field, which shows the same 16 bytes of the file as the hex field, but now as the characters in the Atari ST character set associated with those byte values. *NOTE: There is one exception: the NULL byte is not shown as a space, which would be the Atari character associated with it, but as three horizontal bars. This was done with a purpose: when editing in programs it is very important not to overwrite terminal zeros of strings. Therefore, these must be clearly distinguished from spaces. *NOTE: If 'text' filter is on, only letters, digits and punctuation marks are displayed. (A-Z | a-z | 0-9 | ; | : | . | , | ! | ?) If you are in EDIT and r/w mode the cursor flashes. (Except that in monochrome mode, if the cursor happens to be positioned on a space, the flashing will be invisible) The command/message line shows the mode ZAP is in, and this is also where ZAP asks you to type in additional information, and where messages appear. *** The cursor *** If this blinks, ZAP is in read/write mode. If it is steady, it is not. In the latter case either the file is read-only, or the read only option was specified, or the file was locked by you, or the text filter is active, or ESC mode is on. *** A short history of ZAP *** ZAP was originally written in 1986, by D.A. Gerritsen, Medemblik, The Netherlands. He placed the source in the public domain. The original program was much larger and slower than the current version, as the original author must have been, at least at that time, a beginning C programmer. Nevertheless the program was one of the public domain programs I regularly used, so the idea of trying to improve it came naturally... This task, lightly started, ended in a virtually complete rewrite. ZAP 2.5 is now 60% of its original size and the display is much faster. Many options were added, among which the locking facility, a better commandline editor, the status line, the offset field, a better print facility, a better help facility, and complete mouse support. Every new release of ZAP is given to a few experienced computer users to invite their comments. These are then taken into account as far as possible. ZAP 2.5 was written in Turbo C 1.0, using some 20, mostly small, hand-coded assembler routines to improve size and speed. The C part of the source (ca. 50 K) is available from me on request, the assembler routines only in .lib form. Write to the address below. *** Disclaimer *** Playing with ZAP without backing up the file to be edited first is playing with fire. To my best knowledge ZAP works exactly as documented in this file. It has been extensively tested with correct and incorrect input and was programmed to do the safe thing when in doubt. However, I cannot accept responsibility for any damage which may occur because of the use of it. *** Who to write to *** If you have comments on ZAP that you feel would contribute to a later version, please do not hesitate to contact me - I shall be delighted. Keep in mind that my goal is to keep ZAP small, safe and easy to use. E. van Herk BBS The Dutch Connection: Wakkerstraat 18/I (NL) 01751-13128 1097 CE Amsterdam Leave message to: Bart van Herk The Netherlands. (9600 HST supported) *** Update History *** Changes to version 2.1: - The program sometimes scrolled suddenly when a search line was entered. This has been fixed by setting the VT-52 'no wrap' mode before editing starts, and resetting it to 'wrap' before the program quits. - The program now clears the screen before quitting, as the result when called from a commandline wasn't pretty. Changes to version 2.2: *Thanks to: Ernst Blok and Rob Pont for their intelligent and helpful comments! - The screen is no longer inverted - Some mouse support added - position and chunk start counting at 0 ; - position is now displayed in decimal and hex numbering - more elegant display algorithm - filesize is now displayed. - cursor management now completely under program control, to prevent smudges when the mouse is moved over the text cursor - The cursor blinks if the read/write mode is active. Changes to version 2.4: - Complete reorganization of the command structure into two menus with fully integrated mouse interface. - Complete rewrite of the help facility. - New logo screen - some streamlining of the code. Changes to version 2.5: - The -r flag was not recognized when ZAP was called from the desktop as a .ttp program, because TOS capitalizes the commandstring. ZAP now also recognizes the -R option for this. - A few messages and texts were edited a bit for a more pleasing screen effect. - The program did not not always save the current chunk before quitting; now it does.