* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * S C A N * * * * A ZCPR3-Compatible Buffered Bi-directional * * Video-oriented Text File Display Utility * * For Text and Library Member Files * * * * by * * Terry Hazen * * 21460 Bear Creek Road * * Los Gatos, CA 95030 * * * * Voice.......... (408) 354-7188 * * Saratoga RBBS.. (408) 354-5934 * * Zee-Machine.... (408) 245-1420 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Latest Revision --------------- Version 2.1 - 01/01/90 See SCAN21.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 computer with a Z80 processor and a terminal with addressable cursor, home cursor/clear screen and erase to end-of- line functions. Video highlighting, delete and insert line functions 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 of any size. 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. 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 files such as COM, ?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 Display Mode Commands. To help you extract information from the file being viewed, SCAN allows you to either 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 environment, with an AMPRO standard Z3ENV address of FE00h. ZCPR3.0 users with other Z3ENV locations should install their own Z3ENV address into SCAN using their regular installation method. Non-ZCPR3 users can patch the address to 0000h. While SCAN will run as distributed, it will run even better if delete and insert line terminal control sequences for your terminal are patched into SCAN or installed into an extended Z3TCAP (which specifies terminal control information) located either in SCAN or in the ZCPR3 environment. A Z3TCAP needs to be installed into SCAN before SCAN can be run in non-ZCPR3 environments. For further installation and patching information, SCANINST.DOC contains information on installing a standard Z3TCAP for your terminal into SCAN, SCAN.PAT contains information on the available user patch locations, and Z3TCAP.DOC contains information on the structure of the new extended Z3TCAP. 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 specified name. If no matching file is found, SCAN will look for a library (with an 'LBR' filetype extension) 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 name but with a blank 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 will always show 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 find string, and eliminating the time it takes to reload SCAN from disk. SCAN can also be run using the ZCPR3 GO command whenever a series of files are being viewed, but the find string will be initialized each time SCAN is run using GO. Display Mode Commands --------------------- SCAN has three display modes. Only one mode may be selected at a time. The distribution default WordStar mode, displaying control characters in highlighted video and displaying hard carriage returns, page breaks and indicating lines longer than the screen width, is controlled by the ^OD toggle command. The ZCPR3 display mode, displaying characters appearing between ^A (01H) and ^B (02H) in highlighted video, is controlled by the ^OV toggle command. Turning off both of these display modes results in a vanilla TYPE-like display 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 ............... WordStar DISPLAY MODE TOGGLE. Displays control characters in highlighted video, displays hard carriage returns and indicates lines longer than the screen width at the right margin. Page breaks resulting from form feed characters are also displayed. ^OV ............... ZCPR3 DISPLAY MODE TOGGLE. Displays characters appearing between ^A (01H) and ^B (02H) in highlighted video. Useful for viewing files such as SCAN.HLP as they appear when run under ZCPR3. ............... NO MODE SELECTED. 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. The ZPATCH commands for top and bottom of file and for forward and back one screen are included as an alternate commands set. 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. ^R (<)(,) ......... SCROLL UP (BACK) ONE SCREEN. This command will turn the Printer and File Output modes OFF. ^W (^E) ........... SCROLL UP (BACK) ONE LINE. This command will turn the Printer and File Output modes OFF. ^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. ^Z (^X, RETURN) ... SCROLL DOWN (FORWARD) ONE LINE. ^C (SPACE)(>)(.) .. SCROLL DOWN (FORWARD) ONE SCREEN. ^QC (B) ........... DISPLAY END OF FILE. Displays last screen in file. This command will turn the Printer and File Output modes OFF. 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 find string will only be re-initialized on program startup, the current find 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, however, the find 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 find 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. Find Again begins right after the previous find. If another command has been executed between the Find and Find Again commands, Find Again will start searching beginning with the first character displayed on the current screen. After the search 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 has been 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 find 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 find 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 video highlighting. 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 find string without executing them. ^U ................ CANCEL the search string entry process. Ending the find string entry process: RETURN ............ END the string entry process. 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 the string entry process and match the string exactly as entered. Other 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 find 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 it is ready. 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 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) ...... 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, SCANINST.DOC and Z3TCAP.DOC for information on installing SCAN and patching the following values to match for your terminal and/or system. The distribution defaults are: Z3ENV address............... 0000h Found String Display Line... 13 Program Name................ 'SCAN ' Printer Init String......... Empty Delete Line String.......... Empty Insert Line String.......... Empty Display Lines............... 0 Display Columns............. 0 Display Overlap............. 3 Display Mode................ WordStar Processor Speed............. 0 (defaults to 4 MHZ) Internal Z3TCAP............. Empty =================================================================