CP/M/CPM_CDROM.iso/beehive/compress/ql40.arc/QL-OLD.DOC

Text File | 1991-08-11 | 19KB | 386 lines

--------------------------------------------------------------------
===> For general Usage, please refer to the file QL40.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.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]  [phone]
    Holly Park RCP/M    [Dick Roberts]     [phone]
or US Mail:
    Ross Presser
    209N Haddonview Apts
    Westmont, NJ 08108
Nights: [phone]

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.