* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * S C A N * * * * A ZCPR3-Compatible Buffered Bi-directional * * Video-oriented Text File Display Utility * * For Text and Library Member Files * * * * Copyright (c) 1988-90 * * by * * Terry Hazen * * 21460 Bear Creek Road * * Los Gatos, CA 95030 * * * * Voice.......... (408) 354-7188 * * Zee-Machine.... (408) 245-1420 * * Ladera Znode... (213) 670-9465 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Latest Revision --------------- Version 2.2 - 05/18/90 See SCAN22.HIS for revision details. ================================================================= Overview -------- SCAN is a 6k bi-directional video-oriented text file display utility that uses the basic WordStar command set to control viewing of text files and library member files in both ZCPR3 and CP/M environments. SCAN is designed to view normal text files and library members and will not unsqueeze or uncrunch files. SCAN requires a Z80 computer with a terminal that has addressable cursor, home cursor/clear screen and erase to end-of-line functions. Delete and insert line functions and video highlighting are helpful, but are not required. SCAN allocates all available memory up to the CCP or lowest RSX for text buffers and uses a dynamic buffer allocation process to allow full bi-directional browsing through text files so that the size of the file being viewed is not limited by available memory space. SCAN also allows you to scroll the screen from side to side to allow viewing of lines longer than the screen width, as often found in LST or PRN files. Like QL and VTYPE, SCAN allows you to quickly jump to the end of the file being viewed, a very useful feature when viewing source, LST or PRN files. SCAN has a very fast string find routine and like WordStar, SCAN will allow you to set and quickly return to place markers 0-9. Since SCAN is designed for personal rather than RBBS use, it has no built-in security features. For the same reason, no file types are automatically excluded from viewing, although binary file types such as BIN, COM, HEX, ?Z?, ?Q?, etc, will not produce comprehensible displays. Files may be viewed as straight ASCII text files or in either the WordStar or ZCPR3 display modes, which differ primarily in how they display control characters. The WordStar display mode is the distribution default, but SCAN may be patched to make any one of the three display modes the default. The features of these display modes are described more detail in the section on Video Display Modes. To help you extract information from the file being viewed, SCAN allows you to send the text being viewed to a specified file or to your printer. If present, a user-patchable printer initialization string will be sent to the printer each time the printer function is selected. Installation ------------ SCAN is distributed ready to run in a ZCPR3.3+ environment, with a Z3ENV address of 0000h. ZCPR3.0 users should install their Z3ENV address into SCAN using their regular installation method. While SCAN will run as distributed under a standard Z3TCAP, it will run even better if a VLIB4D (or later) extended Z3TCAP, which has been expanded to include delete and insert line terminal control sequences, is installed into your ZCPR3 environment or directly into SCAN. A Z3TCAP (which specifies terminal control information) needs to be installed into SCAN before SCAN can be run in non-ZCPR3 environments. SCANINST.DOC contains information on using SCANINST to install a Z3TCAP for your terminal into SCAN.COM. ZCNFG14.COM and the configuration file SCAN.CFG may also be used to change some of SCAN.COM's more common user-configurable settings. For further installation and configuration patching information, SCAN.PAT contains information on the available user patch locations. It is also the source code for an overlay to facilitate user customization and contains information on the structure of the new VLIB4D extended Z3TCAP. TCSRC13.DOC contains information on using TCSRC13.COM, a utility that allows you to quickly and easily create commented VLIB4D extended Z3TCAP source code files from existing termname.Z3T files or directly from the Z3TCAP in your environment. Syntax ------ SCAN's command line syntax is: SCAN [dir:]afn - Display text file SCAN [dir:]LBRname[.LBR] - Display library directory SCAN [dir:]LBRname LBRmember - Display library member SCAN is fully ZCPR3 compatible when operating in a ZCPR3 environment, accepting both the DIR: and the DU: forms. SCAN will not accept the DIR: form when operating in a non-ZCPR3 environment. For easier filename entry, you may use wildcards in specifying the filenames, library names or library member names you wish to view. SCAN will display the first file it finds in the directory or library directory matching the ambiguous specification. If you enter a filename with no filetype extension, SCAN will first look for a file with the exact specified name. If no matching file is found, SCAN will look for a library (which has a filetype extension of '.LBR') with the specified library name. If the library is found, SCAN will display the library directory and an invitation to enter the name of a library member for viewing. The use of the '.LBR' filetype is always optional unless a file of the same filename but with an empty filetype extension also exists on the specified directory. While viewing a library member, two of SCAN's exit commands will cause SCAN to exit to the library directory in the same way that you can move from a file back to the main menu in WordStar. When viewing a text file, all exit commands will cause SCAN to exit directly to the system command line. SCAN's HELP screen always shows the correct currently available exit commands. See the section on Exit Commands for more information. SCAN's ^KR command may be used while viewing a file to read in another file without leaving SCAN, retaining the currently active search string, and eliminating the time it takes to reload SCAN from disk. SCAN can also be rerun using the ZCPR3 GO command to view a series of files. Video Display Modes ------------------- SCAN has three video display modes. The ^OD toggle command steps through them in sequence. The distribution default WordStar mode displays control characters in highlighted video. It displays hard carriage returns, page breaks and indicates lines longer than the screen width. The ZCPR3 display mode displays characters appearing between ^A (01H) and ^B (02H) in highlighted video. The ASCII display mode is a vanilla TYPE-like mode that doesn't display any control characters. SCAN may be patched to select any of the three modes as the default display mode. The current display mode is indicated in the STATUS line. ^OD (V) ........... WordStar DISPLAY MODE. Displays control characters in highlighted video, displays hard carriage returns and page breaks resulting from form feed characters. Indicates lines longer than the screen width at the right margin. ZCPR3 DISPLAY MODE. Displays characters appearing between ^A (01H) and ^B (02H) in highlighted video. Doesn't display other control characters or form feed page breaks. Truncates lines longer than the screen width. Useful for viewing files such as SCAN.HLP as they appear when run under the ZCPR3 utility HELP.COM. ASCII DISPLAY MODE. Doesn't display control characters or form feed page breaks. Truncates lines longer than the screen width. Screen Display Commands ----------------------- SCAN uses the basic WordStar command set to control its screen display. To make life a little easier, there are alternates available for several of the SCAN commands. To keep the size of SCAN under 6k, these alternate commands are not shown in the HELP screen, but are shown instead in parentheses in the command summary below. As part of its alternate command set, SCAN supports the ZPATCH commands 'T'=top of file, 'B'=bottom of file, '>'=forward one page and '<'=back one page, as well as the extensions '.'=forward one line and ','=back one line. For users prefering the BGii TYPE command set, the library SCAN22BG.LBR contains SCAN22BG.COM and SCAN22BG.Z80 (an overlay file that modifies SCAN to make SCAN's commands more BGii- compatible.) When paging by screens, SCAN displays a user-patchable number of overlap lines from the previous screen on the new screen as an aid to orientation. When entering commands, the use of the control key is optional, so that entering ^QC is the same as entering QC or ^Q^C. ^QR (T) ........... DISPLAY BEGINNING OF FILE. This command will turn the Printer and File Output modes OFF. ^QC (B) ........... DISPLAY END OF FILE. Displays last screen in file. This command will turn the Printer and File Output modes OFF. ^R (<) ............ SCROLL UP (BACK) ONE SCREEN. This command will turn the Printer and File Output modes OFF. ^C (SPACE)(>) ..... SCROLL DOWN (FORWARD) ONE SCREEN. ^W (^E)(,) ........ SCROLL UP (BACK) ONE LINE. This command will turn the Printer and File Output modes OFF. ^Z (^X)(RETURN)(.) SCROLL DOWN (FORWARD) ONE LINE. ^D (TAB) .......... SCROLL SCREEN RIGHT ONE TAB (8 spaces). Allows you to view lines longer than the screen width. ^S (BACKSPACE) .... SCROLL SCREEN LEFT ONE TAB (8 spaces). Allows you to back up while viewing a long line. (^QS) ............. RESTORE NORMAL LEFT MARGIN. Restores display to normal left margin when you have tabbed right to view a long line. String Find Commands -------------------- Like WordStar, SCAN allows you to search the file text for a specified character string (of up to 45 characters). Since the search string will only be reinitialized on program startup, the current search string will remain active when reading in new files with the ^KR command or while examining different files in a library. When rerunning SCAN with the ZCPR3 GO command, the search string buffer will be initialized each time SCAN is rerun. SCAN uses a form of the very fast Boyer-Moore string search algorithm to allow you to locate a specified text string in the file being viewed (for more information on the Boyer-Moore algorithm, see Peter Martin's PHONE3.LBR.) The search code in SCAN is actually my interpretation of Peter Martin's interpretation of Sedgewicks's interpretation of the Boyer-Moore algorithm, and is based on Martin's description of the algorithm rather than his actual code. Boyer and/or Moore may no longer recognize the results! In any case, the results are very satisfying. The SCAN string search function is over two times faster than WordStar 3.0, over three times faster than VTYPE, and almost six times faster than WordStar 4.0, based on the time required to find an exact case match of a 12 character string found at the end of a 76k text file located on a RAM disk. Due to the nature of the search algorithm, SCAN takes even less time to find longer strings! String searches begin with the first character displayed on the screen. If the last string found is still on the screen, Find Again will start searching from the previous find. If another command has been executed between the Find and Find Again commands, moving the previous find off the screen, Find Again will start searching beginning with the first character displayed on the current screen. After the string has been located in the text, SCAN displays the text with the line in which the string has been located displayed as the thirteenth line (patchable) on the screen, with the search string displayed in highlighted video, if available. If no match is found, SCAN will display the last screen of the file and display the message 'String Not Found...' in the STATUS line. ^QF (F) ........... FIND A CHARACTER STRING. The current search string will remain active while examining different library members in a library or after reading in a new file with the ^KR command. ^L ................ FIND AGAIN. The last find command is repeated as though entered again. ^U ................ CANCEL the find command. This command may be entered at any time during the search. The display will resume at the point in the text where the interruption occurred. Control characters, except for ^[ (ESCAPE), ^M (RETURN) and the editing control characters described below, may be directly entered as part of the search string. As in WordStar, any control character may be entered by first entering ^P. Like WordStar, SCAN recognizes ^A as a wildcard character in the search string, matching any single character in the text. It is entered as described above. This means that you can't search for the ^A (01H) character in the text, which is used in some ZCPR3 files to turn on standout video highlighting. The wildcard character may be changed by patching or with ZCNFG. Like WordStar, SCAN also recognizes several editing commands while entering the search string or while entering filenames or library member names: ^X ................ CANCEL the line as entered so far. ^R ................ RESTORE the line as entered so far. ^S (BACKSPACE) .... MOVE ONE CHARACTER BACK in the line being entered. ^D ................ MOVE ONE CHARACTER FORWARD in the line, redisplaying previously canceled characters. ^P ................ ENTER CONTROL CHARACTER prefix, allowing you to enter control characters such as RETURN into the search string without executing them. ^U ................ CANCEL the search string entry process. Ending the search string entry process: RETURN ............ END STRING ENTRY. Allows you to select the option to ignore the distinction between upper and lower case characters when searching for the specified string. The default is to match the string exactly as entered. ESCAPE ............ END STRING ENTRY and match the string exactly as entered. Place Markers ------------- Place markers provide a convenient means of remembering one or more positions in the text and for quickly returning to any of these positions later. Like WordStar, SCAN allows you to set up to 10 place markers. When a place marker is set, marking the current display screen, the marker number is displayed at the upper left corner of the text display, temporarily overwriting the display of the first 3 text characters. This marker is only temporary, and will disappear if you refresh the screen, as it is displayed only to indicate that you have successfully set or returned to a marker. ^K0-9.............. SET PLACE MARKER. The marker indicated (0-9) is set to the current screen. The marker can not be unset, but can be reset to a different screen at any time. ^Q0-9.............. MOVE TO PLACE MARKER. The display is returned to the specified marker (0-9). If the requested marker has not been set, the command will be ignored. Input and Output Commands ------------------------- ^KR................ READ NEW FILE. Asks for a filename and reads in the new file, replacing the file currently being viewed. Libraries and library members may be specified in the same way as on the command line. This command is the same as exiting SCAN and running it with a new command line, but faster. Any current search string will remain active. ^KW................ FILE OUTPUT TOGGLE. Asks for an unambiguous filename and sends text screens being displayed to the specified file. When an existing filename is selected for file output, you are given the option to overwrite that file. File output will be automatically toggled OFF when any command other than Next Line, Next Page or a lateral scrolling command is selected. No overlap lines will be displayed or sent to the file when in file output mode. Selecting file output will turn the Printer mode OFF. ^P ................ PRINTER TOGGLE. Text screens being displayed are sent to the printer. If the printer is not ready, a message will be displayed in the STATUS line and SCAN will await the next command. The printer will be automatically toggled OFF when any command other than Next Line or Next Page is selected. The screen text will be printed with no left margin. No overlap lines will be displayed or printed when in printer mode. Selecting the printer will turn the File Output mode OFF. An optional printer initialization string may be patched into SCAN to allow you to set your printer to a specific type face or size. If the string exists, it will be send each time the printer is selected. HELP Screen ----------- / (?)(^J) ......... HELP SCREEN TOGGLE. Displays a HELP screen containing a summary of screen display commands. Also useful for refreshing the display. This command will turn the Printer and File Output modes OFF. Exit Commands ------------- The HELP screen will reflect proper current exit command usage. ^KX (ESCAPE)(^QQ) . EXIT TO THE SYSTEM COMMAND LINE. ^KQ, ^KD .......... EXIT TO THE SYSTEM COMMAND LINE (when viewing a file.) - or - EXIT TO THE LIBRARY DIRECTORY (when viewing a library member.) Distribution Defaults --------------------- SCAN is distributed ready to run in a ZCPR3.3+ environment. Users running SCAN in CP/M 2.2, ZCPR3.0 or other environments should consult SCAN.PAT and SCANINST.DOC for information on installing SCAN and patching the following values to match your terminal and/or system. The distribution defaults are: Z3ENV address............... 0000h Processor Speed............. 0 (defaults to 4 MHZ) Display Lines............... 0 Display Columns............. 0 Display Overlap............. 3 Found String Display Line... 13 Display Mode................ WordStar Wildcard Find Character..... ^A Printer Init String......... Empty Internal Z3TCAP............. Empty =================================================================