CP/M

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

/ CP/M / CPM_CDROM.iso / enterprs / cpm / utils / f / ql41.ark / QL-OLD.DOC < prev next >

Wrap

Text File | 1990-04-13 | 19.4 KB | 396 lines

-------------------------------------------------------------------- ===> For general Usage, please refer to the file QL41.DOC. This file contains excerpts which are still relevant from the older QLnn.DOC files, and is included because it contains hints, details, credits, and other miscellaneous information. The version revision history is also here and comprises the latter half of this document. -sgg 08-14-88 -------------------------------------------------------------------- [Excerpts from] QL31.DOC documentation and usage of QL.AZM rev 05-17-88 v3.1 Quick look typer for reasonably sized libraried or unlibraried, crunched, squeezed & normal text and binary files, with optional disk output, for z80 cpu's only under CP/M 2.0 or later. QL was [originally] written by: Nick Dobrinich 4337 West 48 Cleveland, OH 44144 < Release > This code is placed in the public domain. Don't sell it. Don't send money. Don't sue me. Don't claim you wrote it. The code for unsqueezing and uncrunching is copyright 1986 by Steve Greenberg & C.B. Falconer for private non-commercial use. They wrote it and I want to credit them for excellent work. Implementation time was less than 2 hours to add a working uncruncher to QL v1.6 without benefit of a linker. ...... [On Find & Repeat cmnds] Up to 19 hex bytes can be searched for. Only the first byte of any matching strings will be marked in hex/ascii display mode: if a hex find string was given, on the hex side; if ascii, on the ascii side. In text mode, control characters (cr, lf, tab) can't be highlighted, but all printable characters of the found string will be. Don't search for -0d0a in text mode (you already know where they are) or the display will scroll to eof. In hex/ascii display mode, you can search for the end of file marker with -1a. R or C Repeats the find forward to the next page having an occurrence of the find string. Repeat is not circular, but you can go back to page 1 and repeat it. A repeat find will never succeed on the current page and thus can never succeed on page 1 (though Find can succeed on page 1). ...... Z1 assembler notes: If you modify this code, the Z1 assembler requires all condition codes to be in UPPER case: ret z jr c,label ; won't assemble ret Z jr C,label ; will If you try to assemble with 'Z1 QL.AAZ', you will get an out of memory error. Just use 'Z1 QL' and everything will be oky-doke. The QL.PRN file will be quite small (symbol table only), unless you've removed the 'nlist s' statement near the top of the source file. ...... [message: 'Note: Entire file does NOT FIT in memory'] This is a warning message, not an error. We don't do any virtual memory stuff with this program, so if a file is too large to be read entirely into RAM, QL reads (and unsqueezes/uncrunches) as much as possible and displays what it can of the first part of the file. There is no way for QL to go beyond this without paging text to disk, which is too slow. The way to handle this for minimum disk use is to break large files up into 25k or smaller chapters, crunch them and library the crunched chapters together. Unsuccessful finds in partially read files will also give this warning. However, extraction from LBRs will never give this error; when the buffer gets full, it is simply emptied to disk and extraction continues. ..... QL.COM is around 8k and requires a 1k pointer table and 200 bytes or so for variables, leaving 50k or so in a 62k cp/m system. If a file doesn't fit, the page number display will have a trailing + sign (Page 1 of 78+). Squeezed files must fit mostly in memory when unsqueezed. They are identified by a 'Q' as the second letter of the file extension. Since unsqueezing a file is the only way to know how long it will be and that varies according to the compression ratio, which varies according to the kind of text that was squeezed, QL tries to do the right thing with big squeezed files (it shows as much of the first part of the unsqueezed file as possible when it detects the unsqueezed text smashing into the bdos). The only way to tell if a file can be completely unsqueezed by this utility is to try it. No harm can result. Crunched files must also fit mostly in memory when uncrunched, but there is a further constraint: the uncruncher efficiently occupies 24k in a work area just below the bdos. This effectively reduces the size of crunched files QL can handle: in a 62k system, about 25k is the largest uncrunched file that will fit. As in unsqueezing, QL will display as much of the first part of the file as possible. Beyond that, you need another utility. If a compressed file (like QL.AZM, which is not crunched) fails in uncrunch or unsqueeze, it is tried as a normal uncompressed file. All additional memory up to and including ccp if necessary is used as a file buffer. QL will not allow overwrite of bdos and warm boots only when ccp gets smashed. The ccp is always overwritten when working with crunched files. Once the file is loaded, there is no further disk action until exit when, if you're working from a library, all members of that library are again listed. The load and unsqueeze/uncrunch time was put up front because I don't like the disk constantly starting and stopping while I'm reading. Reading and unsqueezing/uncrunching in the background would be nice, but... QL is self-initializing. If you use a replacement version of ccp that has a 'go' command, you can just type 'go fn.ext' or 'go lib' to reuse QL without having to reload it. The only terminal capability required is erase screen and home cursor. Direct bios character output is used to speed display but may be disabled. Half- intensity can be used to display *.c?m library members at reduced intensity. [v4.0 note: Not just C?M anymore, now an entire list of extensions which are typically non-ascii. List is at end of QL.002 and could be modified]. Reverse video can be used to mark matches to finds. Mostly compatible with Wordstar document files. QL will fail to find a string only if the first character to find is the last character of a word, which will have its hi bit set by WS. Most normal finds work ok. If you want to type in the hex bytes, a first character with bit 7 set can also be found. If builders built buildings the way programmers wrote programs, the first woodpecker to come along would destroy civilization. In particular, the find string code is held together with chewing gum and is easy to derail. [Find while in Memory dump] [.. may cause spurious, unpredictable or unrepeatable matches if searching the sextion of memory that contains parts of QL iself, namely it's data area]. Beware of roaming into your roms when core dumping: if you have disk controller roms lurking in high memory, strange things, none of them good, may happen. Finds in page 255 can't succeed. The word count for text files is approximate, based on the simple definition of a word being a string of ascii masked characters >= '0' (30h) and < 80h. Needs more thought. ...... < Credit where it's due > QL was inspired by bishow.asm by Phil Carey, W.F. McGee, H.M. Van Tassell and many others. The unsqueeze code is adapted from lt18, copyrighted by Steven Greenberg and C.B. Falconer, which is a much more versatile program but doesn't permit random access. The uncrunch code is uncrel.mac by Greenberg and Falconer. Kudos to Neil Koozer for his speedy Z1 assembler which halved the time of the basic edit > assemble > crash cycle. ...... My thanks to contributors to the public domain who have taught me much. If you're so inclined, hack away at this to improve and extend the code or to suit your own preferences. -------------------------------------------------------------------- --------------------------------------------------------------------------- QLxx has been through quite a bit since it's original inception, but, for history buffs, here's sort of how it all went: --------------------------------------------------------------------------- <History> ver 4.1 (rjp) 11-29-88 - Separated the numbered-file interface to a separate section, QFC.LIB, and modified LBR routines to permit use of same interface. The interface itself was extended and modified to permit "batch" file selections through use of the () [some files] and * [all files] options, and to permit sorting of the file list from any character in the filename (particularly, sort from 8 to get an extension-separated list). Other changes include a check for odd # of sectors in hex display mode (if found, last page is displayed as a half page), and a speedup of finds during typeout. ver 4.0 (sgg) 08-13-88 - Major overhaul, really too extensive to itemize here. Mostly involved a complete revamping of the user interface with help / status screens; correction and consolidation of the ZCPR related code to allow it to work; some changes in memory allocation from DS to run-time generated pointers; filename alphabetization, some user area support, and some general rearrangement and reformatting of the source, as well as a rewrite of most of the documentation. This rewrite started as a 'simple consolidation' of efforts from various people. Though the scope grew well beyond simple, the efforts of those people was indispensible in it's development. Many thanks to Ben Grey, Bruce Morgen, Ross Presser, Bob Schultz, and driving force Paul Foote. - Steven Greenberg ver 3.1 (rjp) 06-09-88 - Working from QL26 by Bruce Morgen (4/6/88), made compatible with ZCPR3. Setting the equate ZCPR3 to TRUE should make this work; however, I have not tested it, for I do not have access to any ZCPR system. Assembly information, quoted from QL26.AZM, has been placed in the file QL$ZCPR3.DOC. - Added 'S' command to Save library members without decompressing them. - After extracting or saving a file, QL will report the file size in sectors and in K. - A check for out of disk space, omitted by some oversight, was added to the file extraction code. - ALL of the extraction code can be bypassed by setting the option equate EXTR to FALSE. This saves a few K in program size. - Added case-insensitive searching toggle, controlled by 'I' cmd. To do this required that the search be made slower; sorry. It now takes about 3.25 sec to search all of a 60K file, instead of less than .25 sec. - Added ability to select files by number. If you specify an ambiguous filename on the command line, QL will display all the filenames that match and ask you to select one. (If none were found, QL will search for libraries with matching root names, just like it does with unambiguous files. If exactly one matching file was found, it will skip the selection process.) ALL matching files, including LBRs, are available for selection. If an LBR is selected, it will be opened as a library UNLESS you specified .LBR in the ambiguous filename, in which case it will be opened as an ordinary file. When you exit from viewing a file, the selection menu pops up again. - A few cosmetic changes: cleaned up the usage message, added and removed CRLFs to neaten up the display, added "Members in d:library.LBR" message, and displayed default disk in "d>Member (1-xx)" message. ------------------------------------ Bug reports: Leave mail at one of: CRUNCH RCP/M [Steve Greenberg] (201)447-6543 Holly Park RCP/M [Dick Roberts] (201)757-1491 or US Mail: Ross Presser 209N Haddonview Apts Westmont, NJ 08108 Nights: (609)869-0298 ver 3.0 (rjp) 05-17-88 - Incorporated the fix in QL25BFIX.LBR, supplied by an anonymous programmer, which fixes what is probably the last bug in the file extraction code. Changed major revision level to 3. Also, if the "E" command is disallowed (no WHEEL), it will not appear in the help menu. Also included QL25B/30.DIF, a SSED script file for updating ver 2.5b to 3.0. ver 2.5b (rjp) 04-21-88 - Corrected several disastrous bugs in file extraction code. ver 2.5a (rjp) 04-11-88 - Added capability to extract (and decompress) files from libraries with E command (only if WHEEL). Member is extracted to default drive; if file already exists, user is asked whether to purge it. - Moved size of CCP from CHKSUMCCP routine (hard-coded) to CCPSIZE equate. - To recognize the fact that some reverse on/off sequences occupy space on the screen, the flag REVSPACE was added. Set it to the number of spaces to reserve for each REVON and REVOFF command. - Added two instructions in the initializing code to zero the R2 byte in the default FCB. Some CCPs (mine!) do not automatically zero this byte; if it is not zero, the first sector of uncompressed, unlibraried files that match *.?Z? or *.?Q? is not read in properly. - Added ability to display non-displayable control characters with dim-video. This is controlled by the flag CTRLDIMVID. Changed CTRLDISPLAY to CTRLWORDSTAR; added (computed) flag CTRLDUMMY = - Split the source file into two parts to make it easier to edit! Note: I was going to call this QL26, but before I was finished someone had already pre-empted that name. I was NOT going to start my changes over again with QL26. Therefore I am calling this QL25A. ver 2.5 (sgg) 02-28-88 - Corrected a bug which prevented all previous versions from being able to uncrunch a file if the system's BDOS started at an address other than a page boundary or a page boundary plus six. This would cause an "unknown uncrunch error", which wasn't even the "correct" error message due to another bug in the error message reporting code (also fixed). - Eliminated the use of alternate registers and the associated EQUate. Use of the alternate registers conflicted with some systems. Removed redundant register saves and eliminated a subroutine level in the same same area (memory i/o routines). Also: - Added Wordstar-like ability to display control characters not otherwise handled (eg "02" in a file will display as "^B"). - Added ascii FF (formfeed) char to the "legitimate character" list, so documents with a leading formfeed won't come up in hex mode. - Changed most JP's to JR's in UNC.AZM, and removed the extra entrypoints and associated code not used by QL. ==> Many thanks to Ken Reid and Mike Greenhill. ver 2.4 (sgg) 01-25-88 To make QL a viable "online" utility: added BYE detect: adjusts memory limits and inhibits video attribute xmit checks wheel byte: inhibits system COM file and "core" dumps. continuously checks for ^S, etc while running remote. Stronger checking of user keyboard input some synonyms added. Added M80 EQU to allow assembly under M80 / SLR Z80ASM. Used macros so terminal attribute sequences could be relocated to the beg- inning of the file (configuration section) where they logically should be. Other misc. changes. ver 2.3 (njd) 12-27-87 fixed a nasty bug in ws doc file handling and other doc file goofs. added tab expansion to spaces option. added @ marker character for control characters we can't reliably send to a terminal. added truncation toggle command. Removed truncation logic to putc: rtn where it belonged, but not before torturing myself at length with the old scheme. ver 2.2 (njd) 12-12-87 release halted due to a nasty bug in ws doc files. added core dumping option if no file or library name is given. added filename.ext to summary. added summary word count for text files. fixed line counting in ws document files with page breaks. better eof handling for files just larger than available memory. ver 2.1 (sgg) 12-5-87 - Changed display of library member filenames. Now includes the reference #. - Eliminated "File not found" message each time a library was opened. The message will only appear if neither a plain nor .LBR file with the specified name can be found. - Added "Q", escape, and ^K as additional synonyms to existing eXit & ^C for BISHOW, LIST61, and generic compatibility reasons. - Changed code which outputs the uncrunched filename to prevent it from outputting any chars in the header beyond the filename (CR23D compat.) - Added UCHEX equate for those who prefer upper case letters in hex dump. - Took the liberty of removing my own name (and cbf's) and copyright message from the display (still embedded in the code, however). Made some changes to the main help menu as well. - Steven Greenberg ver 2.0 (njd) 12-1-87 included uncrunching capability, courtesy of Greenberg & Falconer. changed unsqueezing method to read & unsqueeze simultaneously, like uncrunch. Can handle much bigger squeezed files. What was I thinking before? added checksum verification of ccp overwrite instead of a lot of bookkeeping. added hex/ascii display of non-text files and as an alternative for text files. added partial display of files too big for available memory. changed the whole find string philosophy. added highlighted display of found strings in text and hex/ascii. added find of hex byte strings when prefaced with '-'. deleted all page tagging code, unnecessary with page number selection. eliminated most self-modifying code. ver 1.6 (njd) set fcb1 r2 field to 0 to avoid random read (bdos fn 33) error 6. capitalized jump, call and return condition codes for Z1 assembler. removed 'title' directive (unsupported by Z1 assembler). added conditional for Z1 assembler to generate a .COM file directly. ver 1.5 (njd) fixed dumb error in deleted member handling. ver 1.4 (njd) removed Member Not Found and substituted numeric choice of members from the library directory. added half-intensity option for *.c?m members. added option for DOS+ bdos call 211. ver 1.3 (njd) added library searching and directory listing capabilities. added unsqueezing and protection from squeezed files that get too big. added option to not use bios console output routine to speed display. added delay code for page number input without <ret>. eliminated scroll on forward paging. added total byte and line summary. made line overlap user configurable. use computed file size to see if file will fit below bdos and if it will overlay ccp instead of reading until collision. fixed single line forward so it adjusts current page as expected. added long line truncation flagging with '>'. ver 1.2 (njd) added page tagging. If usealtregs is true, this feature uses the z80 alternate register set, which may be incompatible with your system, particularly if it is interrupt driven. Set the usealtregs equate false to use fake memory register code (which is slightly longer) and reassemble. Page tagging can be eliminated by setting pagetags equate false. page pointer rtn now looks for lf instead of cr, which is the way it should have been written in the first place. Ah, middle age... during page number jumps, watches for sufficient number of digits for page to jump to. better command parser and clearer program structure. made reentrant for zcpr 'go' cmd by initializing storage. added version numbering. ver 1.1 original for standard text files.