CP/M

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

/ CP/M / CPM_CDROM.iso / beehive / program / szap50.arc / ZAP50.DOC < prev next >

Wrap

Text File | 1990-10-31 | 28.3 KB | 592 lines

*--------------* | SuperZap 5.0 | *--------------* SuperZap is a screen-oriented disk- and file-update utility for CP/M-80. Implementing an intuitive, single-keystroke-driven, menu-assisted interface, it offers straightforward, no-nonsense access to the contents of any data file or disk sector through an array of useful functions. Utilizing SuperZap's powerful facilities, you can o efficiently view and edit the contents of any file or disk sector, even so-called "bad" or corrupted sectors. o easily display ("dump") the data contents of any file to the screen, moving either forward or backward in a paged fashion o quickly search for any string of ASCII characters or sequence of hexadecimal bytes, either within an individual file or on the entire disk SuperZap has two main modes of operation, Directory and Sector. In Directory mode, SuperZap will display an alphabetized list of the filenames in any CP/M user area. You can then selectively view any file's contents in either a paged (Type submode) or sector (Edit submode) fashion. Furthermore, while in Edit submode, you can freely modify the contents of any file, in either hexadecimal or ASCII format, and optionally write the changes back to disk. In Sector mode, SuperZap will display, in both hexadecimal and ASCII format, the contents of any CP/M sector (128 bytes) on any disk whose format is recognized by your computer's BIOS. SuperZap will read and write sectors to and from the disk using BIOS functions directly, thus bypassing the BDOS' safeguards and restrictions. In this way, you can freely modify the contents even of sectors that cause normal CP/M disk operations to fail because of a BDOS error condition. You can thereby attempt repair of "bad" sectors whose control information (e.g., CRC data) has somehow been corrupted, recovering valuable data that would otherwise be lost. To facilitate the repair of damaged sectors (and as a safety feature during sector editing), SuperZap provides a handy "clipboard" to which you can copy the contents of any file or disk sector, then transfer these contents to any other file or disk sector on either the current or another disk. Thus, you might be able restore a damaged or "blown" sector simply by replacing its invalid data with sector data from a reliable source. SYSTEM REQUIREMENTS ------------------- SuperZap is written in optimized Z80 Assembler and is designed to run under either CP/M 2.2 or CP/M 3 ("Plus") on any compatible computer that employs or emulates a Zilog Z80 CPU. SuperZap requires a terminal that supplies a video display area of at least 80 columns by 24 lines. To install SuperZap for your CP/M computer, you will need to consult a detailed listing of your terminal's screen-control codes for the following functions: cursor left \ cursor right \ cursor up \ cursor down > (must all be single characters) tab / escape / del / clear screen \ clear to end of line \ inverse video \ normal video \ highlight on \ highlight off > (can each be multiple characters, blinking on / e.g., escape sequences) blinking off / cursor on / cursor off / direct cursor addressing / You will then need to edit SuperZap's source code, inserting these terminal- specific codes in their proper places by using your favorite text processor. Note that if certain of the multiple-character sequences are not available on your terminal, you can substitute one of the others (e.g., "highlight on" for "blinking on") or deactivate them by using a zero (null string). Finally, you will have to assemble the complete program with a Z80 macro assembler, either Microsoft's Macro-80 ("M80") or the popular public-domain Z80MR. For convenience of installation, along with the main source-code file ZAP50.MAC, a separate, shorter file containing all the terminal-specific parameters is included here in the correct format for each of these macro assemblers: ZAP.MAC for Macro-80 and ZAP.AZM for Z80MR. (In fact, Z80MR itself is also supplied!) Printing out either one of these files as a first step will make the overall installation task somewhat easier, besides acquainting you with some of the long development history of this program. Installation with Macro-80 ========================== Assembling SuperZap is a two-step operation: 1. Generate a relocatable (.REL) file from the source code; a typical command line for Macro-80 is M80 =ZAP/M where the (optional) /M switch specifies that data-storage areas should autoMatically be initialized (i.e., filled with zeros). 2. Link the .REL file into executable object code; a typical command line for Link-80 is L80 ZAP,ZAP/N/E where the /N switch Names the object-code (default is .COM) file and the /E switch instructs Link-80 to Exit back to CP/M upon completion. Installation with Z80MR ======================= Assembling SuperZap is a two-step operation: 1. Generate a hexadecimal (.HEX) machine-code file from the source code; a typical command line for Z80MR is Z80MR ZAP.AAZ ^^^ ||| ||+--- destination drive for the listing (.PRN) file || (i.e., A thru P, X = console, Z = no file) |+---- destination drive for the .HEX file +----- source drive for the .AZM file 2. Load the resulting .HEX file into a command (.COM) file; a typical command line for LOAD.COM (the standard CP/M object-code generator) is LOAD ZAP RUNNING SuperZap ---------------- SuperZap can be invoked from the CP/M command line in several ways (each is terminated by pressing RETURN or ENTER). In the simplest case of typing only the program's name, ZAP will start up SuperZap in Directory mode in the current user area on the current drive, or ZAP d: will start up SuperZap in Directory mode on the specified drive. ZAP [d:]afn will start up SuperZap in Directory mode on the optionally specified drive, but additionally specifying an ambiguous filename ("afn"), e.g., "*.COM", will cause SuperZap to apply a mask to the directory list, such that only those filenames which satisfy the ambiguity will be displayed. Being even more specific, ZAP [d:]ufn will start up SuperZap in Edit submode on the particular file specified by the unambiguous filename ("ufn") on the optionally specified or current drive. Finally, ZAP [d:]DSK: will start up SuperZap in Sector mode on the optionally specified drive; the first sector in the CP/M directory area will immediately be displayed. DIRECTORY MODE -------------- Upon entering Directory mode, the following menu will appear at the top of the screen: ^? Cursor left N Next directory page D Change Drive ^? Cursor right P Previous directory page S Select track/Sector ^? Cursor up M Set directory Mask E Edit file ^? Cursor down U Change User number T Type file TAB Next file (current: 0) Z Exit SuperZap followed by an alphabetized listing of the first 32 filenames in the CP/M directory, with a header showing the current directory mask in use. The cursor will now be positioned next to the first filename in the list. Use the left, right, up, and down cursor/arrow keys (as installed) to move quickly from one filename to another; hit the TAB key to move through the filenames in alphabetical order; or hit RETURN to jump to the first filename on the next line (cycling back to the top). If there are more than 32 filenames in the CP/M directory, only the first block ("page") of the directory will be displayed. Hit 'N' to view the next directory page, or hit 'P' to view the previous page. Hit 'M' to change the current mask that SuperZap is applying to the directory list. The following menu will appear at the top of the screen: ^? Cursor left ^V Insert on/off TAB Toggle name/type ^? Cursor right DEL Delete character ESC Use current mask followed by an editable display of the current mask: File name ==> ???????? <= File type ==> ??? <= Use the left and right cursor/arrow keys (as installed) to move about the field of the ambiguous file name or type (switching to the next field in a circular fashion); hit the TAB key to toggle between these two fields. Use the DEL key to delete characters and close up the space; hit '^V' (CTRL-V) to toggle insert on and off for changing or adding characters. Type an asterisk ('*') to fill from the cursor position to the end of the field with wildcards ('?') and switch immediately to the other field. Hit the spacebar to space- fill ("blank") from the cursor position to the end of the field and switch immediately to the other field. While in the file-name field, type a period ('.') to blank to the end of the field and switch immediately to the file-type field. When you are done, press RETURN to enter a new mask and return to Directory mode; or hit ESC to revert to the current mask. Back in Directory mode, hit 'U' to change to a new CP/M user area; the following prompt will appear: Enter hex user number or press ESC ==> Type a valid hexadecimal digit (0,1,...E,F) to change to the corresponding user area 0 through 15 and view a new directory list, or hit ESC to abort the numerical selection and return to the current list (the current user number is shown in the menu panel). Hit 'D' to select a new drive; the following prompt will appear: Enter drive letter or press ESC ==> Type a valid drive letter to enter Directory mode on the specified drive, or hit ESC to abort the selection and return to the current directory list. Hit 'S' to enter Sector mode on the current drive (as described below). Hit 'E' to enter Edit submode, or hit 'T' to enter Type submode, on the file next to whose name the cursor is positioned (as described below). Finally, hit 'Z' to end your SuperZap session and exit back to the CP/M prompt. SECTOR MODE ----------- Upon entering Sector mode, the following menu will appear at the top of the screen: N Next sector T Select Track A Find ASCII string P Previous sector S Select Sector H Find Hex sequence I Next track B Select Block L Return to file List O Previous track D Select Drive Z Exit from SuperZap C Clipboard operations Clipboard :- Empty E Edit sector followed by a display, in both hexadecimal and ASCII format, of the contents of the first CP/M sector (128 bytes) in the directory area of the current disk. Any ASCII characters with their high (eighth) bit set will be shown in inverse video, for contrast. Heading this display is a listing of the track, sector, and block numbers (in hexadecimal) for the current disk sector, along with the current drive designation: Current Track Current Sector Current Block Current Drive 0001 0000 0000 A: Offset 0 1 2 3 4 5 6 7 8 9 A B C D E F -----ASCII------ 000000 00 43 4F 50 59 20 20 20 20 43 4F 4D 00 00 00 1E |.COPY COM....| 000010 02 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 000020 00 44 20 20 20 20 20 20 20 43 4F 4D 00 00 00 17 |.D COM....| 000030 03 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 000040 00 44 41 20 20 20 20 20 20 43 4F 4D 00 00 00 0F |.DA COM....| 000050 04 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 000060 00 44 44 54 5A 20 20 20 20 43 4F 4D 00 00 00 36 |.DDTZ COM...6| 000070 05 06 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| where "offset" indicates the relative location of each byte within the current sector. The cursor will now be positioned after a prompt to select the next operation from the menu: Select option ==> Hit 'N' to view the next disk sector, or hit 'P' to view the previous sector (in a circular fashion). Hit 'I' to move to the next disk track (the sector number remains the same), or hit 'O' to move to the previous track (in a circular fashion). Hit 'T', 'S', or 'B' to select a specified track, sector, or block number, respectively, for sector display. Enter the number in hexadecimal; use the backspace key for corrections. When you are done, press RETURN; or hit ESC to abort the numerical selection and return to the current sector display. Hit 'D' to enter Sector mode on a specified drive; type a valid drive letter, or hit ESC to abort the selection and return to the current sector display. Searching the Disk ================== Hit 'A' to find a specified string of ASCII characters on the disk, starting from the current sector. At the prompt "Find: ", enter up to 20 ASCII characters (including TABs); use the backspace or left cursor/arrow key to move backward in the string (skipping over but not deleting characters), and use the DEL key to delete characters and close up the space. When you are done, press RETURN to start searching for an ASCII string made up of all the characters up to the cursor position; or hit ESC to abort the search operation and return to the current sector display. SuperZap will scan the disk, sector by sector, stopping when it finds an occurrence of the specified string; a flashing pointer '->' will indicate the string's beginning location within the ASCII field of the sector display, and you will then be prompted whether to continue searching for the next occurrence. Hit 'Y' to continue, or hit 'N' to stop the search operation and return to Sector mode on the sector within which the string was just found. While entering an ASCII string to find, you can also recover a previously typed string by using the right cursor/arrow key; the previous string will reappear, character by character, facilitating repetitive searches on the same string or variations thereof. Hit 'H' to find a specified sequence of hexadecimal bytes on the disk, starting from the current sector. At the prompt "Find: ", enter up to 20 bytes in hexadecimal digits (0,1,...E,F); use the backspace key for correc- tions. When you are done, press RETURN to start the search operation, or hit ESC to abort the search and return to the current sector display. SuperZap will scan the disk, sector by sector, stopping when it finds an occurrence of the specified sequence; a flashing pointer '->' will indicate the sequence's beginning location within the hexadecimal field of the sector display, and you will be prompted whether to continue searching for the next occurrence. Hit 'Y' to continue, or hit 'N' to stop the search operation and return to Sector mode on the sector within which the sequence was just found. If the specified sequence is not found anywhere on the disk, SuperZap will redisplay the first sector in the CP/M directory area. Striking any key during an ongoing search operation will interrupt SuperZap's progress, and you then will be prompted to hit another key to return to Sector mode at the point where the first keystroke was detected. Back in Sector mode, hit 'E' to enter Edit submode on the current disk sector (as described below). Finally, hit 'L' to return to Directory mode on the current drive; or hit 'Z' to end your SuperZap session and exit back to the CP/M prompt. Editing a Disk Sector ===================== Upon entering Edit submode from Sector mode, the following menu will appear at the top of the screen: ^? Cursor left CR New line ^? Cursor right TAB Toggle hex/ASCII field ^? Cursor up ^W Write changes to disk ^? Cursor down ^Q Quit and cancel changes followed by the same header and sector display as before, but now with the cursor positioned on the first hexadecimal byte in the current sector. Use the left, right, up, and down cursor/arrow keys (as installed) to move around within this field; hit the TAB key to toggle between the hexa- decimal and ASCII fields; or hit RETURN to jump to the beginning of the next line in either the hexadecimal or ASCII field (cycling back to the top). While within the hexadecimal field, typing any valid hexadecimal digit (0,1,...E,F) will immediately change the value of the current byte and advance the cursor. While within the ASCII field, typing any valid ASCII key will immediately replace the current character and advance the cursor. Note that the corresponding byte or character in the opposite field will also change immediately. Illegal keystrokes in either field will simply generate a beep. Finally, hit '^W' (CTRL-W) to write the current sector back to the disk, along with any hexadecimal or ASCII changes you might have made while in Edit submode, and return to Sector mode on the freshly edited sector; or hit '^Q' (CTRL-Q) to discard any changes and exit Edit submode back to the current sector display. Because SuperZap reads and writes disk sectors by direct BIOS calls, bypassing the BDOS' disk functions, you can view and edit even "bad" sectors that would otherwise be unreadable from CP/M. Oftentimes, a "bad" sector can be made normally readable by simply writing it back to the disk, thereby recovering its data contents for subsequent file operations. You'll be glad to have SuperZap's scalpel-like precision at your disposal if and when the time comes for such delicate "disk surgery." Clipboard Operations ==================== As an added safety feature, you may find it useful first to copy the contents of the current sector to the clipboard before entering Edit submode. Hit 'C' to activate the clipboard manager; the following menu will appear at the top of the screen: C Copy current sector to clipboard X Exchange current sector with clipboard ESC Return to sector display followed by a header showing the status of both the current sector and the clipboard, by drive designation, track, and sector number (in hexadecimal), along with the contents (if any) of the clipboard in the same format as for a sector display: Current :- Drive A: Track 0001 Sector 0000 Clipboard :- Empty At the option prompt, hit 'C' again to copy the contents of the current sector to the clipboard and immediately return to Sector mode. The menu panel will now be updated to show the current contents of the clipboard, by drive designation, track, and sector number (in hexadecimal). Hit 'X' to exchange ("swap") the current sector with the clipboard. SuperZap will actually write the contents of the clipboard (it must not be empty) to the current disk sector, copy the previous sector contents to the clipboard, and return you to Sector mode with the newly exchanged contents displayed. Besides allowing you to restore the original contents of a disk sector even after editing it, this option also enables you to copy the con- tents of one disk sector to any other, whether on the same or a different drive. Hit ESC to return to Sector mode without performing any clipboard operation. Back in Sector mode, hit 'L' to return to Directory mode on the current disk; or hit 'Z' to end your SuperZap session and exit back to the CP/M prompt. Editing a File Sector ===================== Back in Directory mode, select a file to edit by positioning the cursor next to its name in the file list, and then hit 'E'. The following menu will appear at the top of the screen: N Next sector T Top of file L Return to file List P Previous sector B Bottom of file Z Exit from SuperZap S Select sector A Find ASCII string C Clipboard operations H Find Hex sequence E Edit sector Clipboard :- Empty followed by a display, in both hexadecimal and ASCII format, of the contents of the first CP/M sector (128 bytes) of the specified file. Any ASCII char- acters with their high (eighth) bit set will be shown in inverse video, for contrast. Heading this sector display is a listing of the current drive and filename, the access privilege (R/W = read/write, R/O = read/only), the current sector number (in hexadecimal), and the load address (starting at 0100H for a .COM file) or file offset (starting at 0000H for all others): File Name Access Current Sector Load Address A:ZAP .COM R/W 0000 000100 Offset 0 1 2 3 4 5 6 7 8 9 A B C D E F -----ASCII------ 000100 C3 17 02 5A 33 45 4E 56 01 1A 01 18 06 1B 42 30 |C..Z3ENV......B0| 000110 1B 42 31 06 1B 43 30 1B 43 31 03 1B 42 31 03 1B |.B1..C0.C1..B1..| 000120 43 31 06 1B 42 30 1B 42 32 06 1B 43 30 1B 43 32 |C1..B0.B2..C0.C2| 000130 03 1B 42 34 03 1B 43 34 02 1B 3D 01 20 20 01 80 |..B4..C4..=. ..| 000140 3E 0A 0D 0D 8D EA 2E 00 21 53 75 70 65 72 5A 61 |>....j..!SuperZa| 000150 70 20 35 2E 30 00 00 00 00 FF 00 00 00 00 00 00 |p 5.0...........| 000160 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 000170 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 3F |...............?| where "offset" indicates the relative location of each byte within the current file. The cursor will be now positioned after a prompt to select the next operation from the menu: Select option ==> Hit 'N' to view the next file sector, or hit 'P' to view the previous sector. Hit 'S' to select a specified sector number for display. Enter the number in hexadecimal; use the backspace key for corrections. When you are done, press RETURN; or hit ESC to abort the numerical selection and return to the current sector display. Hit 'T' to jump to the top of the file, or hit 'B' to jump to the bottom ("end of file"). Hit 'A' to find a specified string of ASCII characters within the file, or hit 'H' to find a specified sequence of hexadecimal bytes. SuperZap will operate exactly the same as when searching the disk from Sector mode, except that now the search's range is limited to the current file. If SuperZap reaches the end of the file without finding an occurrence of the specified string or sequence, you will be prompted to hit 'T' to redisplay the first sector ("top") of the file; hitting any other key will cause SuperZap to display the last sector ("bottom") of the file. Hit 'E' to enter Edit submode on the current file sector, but only if the access privilege is read/write (R/W). SuperZap will operate exactly the same as when editing a disk sector, except that now file reads and writes are through normal BDOS functions, and so SuperZap can be thwarted if it happens to encounter a "bad" sector. In such a circumstance, you will need to note the precise number of the troublesome sector and then access the file data indirectly through Sector mode, specifying its CP/M block number. Hit 'C' to activate the clipboard manager, exactly as in Sector mode. Upon returning to Edit submode, the menu panel will be updated to show the current contents of the clipboard, now by drive designation, filename, and sector number (in hexadecimal). Finally, hit 'L' to return to Directory mode on the current disk; or hit 'Z' to end your SuperZap session and exit back to the CP/M prompt. Typing a File ============= Back in Directory mode, select a file to type by positioning the cursor next to its name in the file list, and then hit 'T'. The following menu will appear at the top of the screen: N Next page F Forward paging S Select Sector P Previous page B Backward paging L Return to file List G Go to page No. T Top of file Z Exit from SuperZap followed by a display of the first 16 lines ("page") of the file's contents. As in Sector mode, any ASCII characters with their high (eighth) bit set will be shown in inverse video, for contrast. Heading this page display is a listing of the drive designation and filename, the page number (in decimal), and the current ranges of sectors (in hexadecimal) and lines (in decimal): File: A:ZAP .MAC Page 0001 Sectors 0000-0002 Lines 0001-0016 TITLE SuperZap - CP/M Disk Utility ;----------------------------------------------------------------------------- ; ; SuperZap - A screen-oriented disk editor for CP/M-80 ; ; Usage: ; ZAP start in full directory of current drive/user ; ZAP [d:] start in full directory on selected drive ; ZAP [d:]afn start with directory mask on selected drive ; ZAP [d:]ufn start in file-relative view/edit mode ; ZAP [d:]DSK: start in sector-relative view/edit mode ; ; Created by: ; W.M. Davidson & H.J. Sheldrake ; 18 Dean Park Cr. For .COM files, a "line" consists simply of 79 consecutive characters, displayed without format; thus, typing a .COM file amounts to a screen dump of its contents. For all other types of files, SuperZap will expand tabs and break lines at a carriage return (including any special end-of-line markers, as installed), so that most text files will appear as normal. SuperZap's Type submode is provided mostly for quick scanning of a file's contents, to locate any ASCII strings of interest or other embedded patterns. The particular points of interest can then be noted by sector number for closer scrutiny in Edit submode. Hit 'N' to view the next page of the file, or hit 'P' to view the previous page. Hit 'F' to page forward rapidly through the file without viewing the contents of each page; hit any key to halt paging at a page, sector, or line number shown in the running counters. Likewise, hit 'B' to page rapidly backward through the file. Hit 'G' to go to and view a specified page number. Enter the number in decimal; use the backspace key for corrections. When you are done, press RETURN; or hit ESC to abort the numerical selection and return to the current page display. If it has not already done so, SuperZap first will page forward through the entire file to establish a "queue," and then display the specified page. (Unlike with 'F' and 'B', this paging operation is not interruptible.) Hit 'S' to select a specified sector number for display within the paged format. Enter the number in hexadecimal; use the backspace key for correc- tions. When you are done, press RETURN; or hit ESC to abort the numerical selection and return to the current page display. If it has not already done so, SuperZap will first page forward through the entire file to establish a "queue," and then display the page containing the specified sector. If this happens to fall on a page boundary, you may have to page forward or backward to see the rest of the sector's contents. Hit 'T' to redisplay the first page ("top") of the file. Finally, hit 'L' to return to Directory mode, or hit 'Z' to end your SuperZap session and exit back to the CP/M prompt.